/ Hex Artifact Content
Login

Artifact 364515dd186285f3c01f5cab42e7db7edc47c70e87b6a25de389a2e6b8c413fd:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5a70: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5a90: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ab0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ad0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b00: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b10: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b30: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5b40: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5b50: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5b60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5b70: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 44  QLITE_CANTOPEN_D
5b80: 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28 53  IRTYWAL       (S
5b90: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5ba0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5bb0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5bc0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5bd0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5c00: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5c20: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5c40: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5c60: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5c80: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5ca0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5cc0: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5cd0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5ce0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5cf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d00: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e  _READONLY_CANTIN
5d10: 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  IT       (SQLITE
5d20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c  _READONLY | (5<<
5d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d40: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45  TE_READONLY_DIRE
5d50: 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49  CTORY      (SQLI
5d60: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36  TE_READONLY | (6
5d70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5d80: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5d90: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5da0: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5db0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5dd0: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5de0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5df0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5e00: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e10: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5e20: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e30: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5e50: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5e60: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5e70: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e90: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5ea0: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5eb0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5ec0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ed0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5ee0: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5ef0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f00: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5f10: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5f20: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5f30: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f40: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f60: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5f80: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5f90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fa0: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5fb0: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5fc0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5fd0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5fe0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5ff0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
6000: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
6010: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
6020: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6030: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
6040: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6050: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
6060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6070: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
6080: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
6090: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
60a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
60b0: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
60c0: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
60d0: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
60e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
60f0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
6100: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
6110: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
6120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
6130: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
6140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
6150: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  H | (1<<8)).#def
6160: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f  ine SQLITE_OK_LO
6170: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20  AD_PERMANENTLY  
6180: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     (SQLITE_OK | 
6190: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
61a0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
61b0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
61c0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
61d0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
61e0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
61f0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
6200: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
6210: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
6220: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
6230: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
6240: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
6250: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6260: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
6270: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6280: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
6290: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62a0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
62b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
62c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
62d0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
62e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62f0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
6300: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6310: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6320: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
6330: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6340: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
6350: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6360: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6370: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
6380: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
6390: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
63a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63b0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
63c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
63d0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
63e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63f0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6410: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
6420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6430: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6440: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6450: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
6460: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6470: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6480: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
6490: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64a0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
64b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
64c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
64d0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
64e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
64f0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6510: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
6520: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6530: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6550: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6560: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
6570: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6580: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6590: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
65a0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
65b0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
65c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65d0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
65e0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
65f0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6600: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6610: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
6620: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6630: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6640: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6650: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6660: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6670: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6680: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6690: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
66a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
66b0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
66c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
66d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66e0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
66f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
6700: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6710: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6720: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6730: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6740: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6750: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6760: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6780: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6790: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
67a0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
67b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
67d0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
67e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
67f0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6800: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
6810: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6820: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6830: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6840: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6850: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6860: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6870: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6880: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
6890: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
68a0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
68b0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
68c0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
68d0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
68e0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
68f0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
6900: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
6910: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
6920: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6930: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6940: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6950: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6960: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6970: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6980: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6990: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
69a0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
69b0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
69c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
69d0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
69e0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
69f0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6a00: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6a10: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6a20: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6a30: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6a40: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6a50: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6a60: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6a70: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6a80: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6a90: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6aa0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6ab0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6ac0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6ad0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6ae0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6af0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6b00: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6b10: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6b20: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6b30: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6b40: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6b50: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6b60: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6b70: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6b80: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6b90: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6ba0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6bb0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6bc0: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6bd0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6be0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6bf0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6c00: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6c10: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6c20: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6c30: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6c40: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6c50: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6c60: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6c70: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6c80: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6c90: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6ca0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6cb0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6cc0: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
6cd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6ce0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6cf0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6d00: 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  es that a file c
6d10: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6d20: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6d30: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
6d40: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
6d50: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
6d60: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
6d70: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
6d80: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6d90: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6da0: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6db0: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6dc0: 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eges..**.** The 
6dd0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
6de0: 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  CH_ATOMIC proper
6df0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ty means that th
6e00: 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20  e underlying.** 
6e10: 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f  filesystem suppo
6e20: 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70  rts doing multip
6e30: 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  le write operati
6e40: 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77  ons atomically w
6e50: 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69  hen those.** wri
6e60: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
6e70: 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b  e bracketed by [
6e80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
6e90: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
6ea0: 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
6eb0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
6ec0: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23  MIC_WRITE]..*/.#
6ed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ee0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6ef0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6f00: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6f10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6f20: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
6f30: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
6f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6f50: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
6f60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6f70: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
6f80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6f90: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6fa0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
6fb0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6fc0: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
6fd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
6fe0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6ff0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
7000: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7010: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
7020: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7030: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
7040: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
7050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7060: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
7070: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7080: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
7090: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
70a0: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
70b0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
70c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
70d0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
70e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
70f0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
7100: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
7110: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
7120: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
7130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7140: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
7150: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
7160: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7170: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
7180: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
7190: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
71a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
71b0: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
71c0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
71d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71e0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
71f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30  IC           0x0
7200: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
7210: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
7220: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
7230: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
7240: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
7250: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
7260: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
7270: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
7280: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
7290: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
72a0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
72b0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
72c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
72d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
72e0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
72f0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
7300: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
7310: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
7320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7330: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
7340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7350: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
7360: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
7370: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7380: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
7390: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
73a0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
73b0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
73c0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
73d0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
73e0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
73f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7400: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
7410: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
7420: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
7430: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
7440: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
7450: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
7460: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7470: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
7480: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
7490: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
74a0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
74b0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
74c0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
74d0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
74e0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
74f0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
7500: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
7510: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
7520: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7530: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
7540: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
7550: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
7560: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
7570: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7580: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7590: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
75a0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
75b0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
75c0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
75d0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
75e0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
75f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
7600: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
7610: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
7620: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
7630: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7640: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
7650: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7660: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
7670: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7680: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7690: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
76a0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
76b0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
76c0: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
76d0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
76e0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
76f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
7700: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7710: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7720: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7730: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7740: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7750: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7760: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7770: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7780: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7790: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
77a0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
77b0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
77c0: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
77d0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
77e0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
77f0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
7800: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
7810: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7820: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7830: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7840: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7850: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7860: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7870: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7880: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7890: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
78a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
78b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
78c0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
78d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
78e0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
78f0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
7900: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7910: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
7920: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7930: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7940: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7950: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7960: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7970: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7980: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7990: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
79a0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
79b0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
79c0: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
79d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
79e0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
79f0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7a00: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7a10: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
7a20: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7a30: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7a40: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7a50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7a60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7a70: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7a80: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7a90: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7aa0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7ab0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7ac0: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7ad0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7ae0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7af0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7b00: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7b10: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
7b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7b30: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7b40: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7b50: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7b60: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7b70: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7b80: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7b90: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7ba0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7bb0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7bc0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7bd0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7be0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7bf0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7c00: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7c10: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
7c20: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7c30: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7c40: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7c50: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7c60: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7c70: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7c80: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7c90: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7ca0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7cb0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7cc0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7cd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7ce0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7cf0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7d00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7d10: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
7d20: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7d30: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7d40: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7d50: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7d60: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7d70: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7d80: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7d90: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7da0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7db0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7dc0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7dd0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7de0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7df0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7e00: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7e10: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
7e20: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7e30: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7e40: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7e50: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7e60: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7e70: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7e80: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7e90: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7ea0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7eb0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7ec0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7ed0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7ee0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7ef0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7f00: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7f10: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
7f20: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
7f30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
7f40: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
7f50: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
7f60: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
7f70: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7f80: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7f90: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7fa0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7fb0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7fc0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7fd0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
7fe0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
7ff0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
8000: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
8010: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
8020: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8030: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
8040: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8050: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
8060: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8070: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
8080: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8090: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
80a0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
80b0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
80c0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
80d0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
80e0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
80f0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
8100: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
8110: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
8120: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
8130: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
8140: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
8150: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
8160: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
8170: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
8180: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
8190: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
81a0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
81b0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
81c0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
81d0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
81e0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
81f0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
8200: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
8210: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
8220: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
8230: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8240: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
8250: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
8260: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
8270: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8280: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
8290: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
82a0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
82b0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
82c0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
82d0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
82e0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
82f0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
8300: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
8310: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
8320: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
8330: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
8340: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
8350: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
8360: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
8370: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
8380: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
8390: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
83a0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
83b0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
83c0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
83d0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
83e0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
83f0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
8400: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
8410: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
8420: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
8430: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
8440: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
8450: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
8460: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
8470: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
8480: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
8490: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
84a0: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
84b0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
84c0: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
84d0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
84e0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
84f0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
8500: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8510: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
8520: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8530: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8540: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8550: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8560: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
8570: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
8580: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
8590: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
85a0: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
85b0: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
85c0: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
85d0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
85e0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
85f0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
8600: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
8610: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
8620: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8630: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8640: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8650: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
8660: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
8670: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
8680: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
8690: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
86a0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
86b0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
86c0: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
86d0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
86e0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
86f0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
8700: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
8710: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8720: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8730: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8740: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8750: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8760: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8770: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8780: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8790: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
87a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
87c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
87e0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
87f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8800: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
8810: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8820: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8830: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8840: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8850: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8860: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c  EQUENTIAL].** <l
8870: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8880: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
8890: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20  N_OPEN].** <li> 
88a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
88b0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
88c0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
88d0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
88e0: 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  LE].** <li> [SQL
88f0: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
8900: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ATOMIC].** </ul>
8910: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
8920: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8930: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8940: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8950: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8960: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8970: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8980: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8990: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
89a0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
89b0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
89c0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
89d0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
89e0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
89f0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8a00: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8a10: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8a30: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8a40: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8a50: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8a60: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8a70: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8a80: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8a90: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8aa0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8ab0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8ac0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8ad0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8ae0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8af0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8b00: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8b10: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8b20: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8b30: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8b40: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8b50: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8b60: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8b70: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8b80: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8b90: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8ba0: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8bb0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8bc0: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8bd0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8be0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8bf0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8c00: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8c10: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8c20: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8c30: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8c40: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8c50: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8c60: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8c70: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8c80: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8c90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8ca0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8cb0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8cc0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8cd0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8ce0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8cf0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8d00: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8d10: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8d20: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8d30: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8d40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8d50: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8d60: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8d70: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8d80: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8d90: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8da0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8db0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8dc0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8dd0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8de0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8df0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8e00: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8e10: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8e20: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8e30: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8e40: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8e50: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8e60: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8e70: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8e80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8e90: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8ea0: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8eb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8ec0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8ed0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8ee0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8ef0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8f00: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8f10: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8f20: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
8f30: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8f40: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8f50: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
8f60: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
8f70: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
8f80: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
8f90: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
8fa0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
8fb0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8fc0: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
8fd0: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
8fe0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
8ff0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
9000: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
9010: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
9020: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
9030: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
9040: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9050: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9060: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
9070: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
9080: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9090: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
90a0: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
90b0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
90c0: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
90d0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
90e0: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
90f0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
9100: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
9110: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
9120: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
9130: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
9140: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
9150: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
9160: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
9170: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
9180: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
9190: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
91a0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
91b0: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
91c0: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
91d0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
91e0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
91f0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
9200: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
9210: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
9220: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
9230: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
9240: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9250: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
9260: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
9270: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9280: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
9290: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
92a0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
92b0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
92c0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
92d0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
92e0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
92f0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
9300: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
9310: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
9320: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
9330: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
9340: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
9350: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
9360: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9370: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
9380: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
9390: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
93a0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
93b0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
93c0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
93d0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
93e0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
93f0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
9400: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
9410: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
9420: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
9430: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
9440: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
9450: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
9460: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
9470: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
9480: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9490: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
94a0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
94b0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
94c0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
94d0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
94e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
94f0: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
9500: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
9510: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
9520: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
9530: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
9540: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
9550: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
9560: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
9570: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
9580: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
9590: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
95a0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
95b0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
95c0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
95d0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
95e0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
95f0: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
9600: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9610: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9620: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
9630: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9640: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
9650: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
9660: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
9670: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
9680: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
9690: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
96a0: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
96b0: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
96c0: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
96d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
96e0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
96f0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
9700: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
9710: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
9720: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
9730: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
9740: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
9750: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
9760: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
9770: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
9780: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
9790: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
97a0: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
97b0: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
97c0: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
97d0: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
97e0: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
97f0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
9800: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9810: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9820: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9830: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9840: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
9850: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9860: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
9870: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9880: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9890: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with 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 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
98e0: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
98f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9900: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
9910: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9920: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
9930: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
9940: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
9950: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
9960: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9970: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
9980: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
9990: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65   journal file (e
99a0: 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f  ither.** the [ro
99b0: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20  llback journal] 
99c0: 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68  or the [write-ah
99d0: 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20  ead log]) for a 
99e0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
99f0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9a00: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
9a10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9a20: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9a30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9a40: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9a50: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
9a60: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
9a70: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9a80: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
9a90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9aa0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9ab0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9ac0: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
9ad0: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
9ae0: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
9af0: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
9b00: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
9b10: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
9b20: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
9b30: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
9b40: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
9b50: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
9b60: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
9b70: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
9b80: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
9b90: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9ba0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9bb0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
9bc0: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
9bd0: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
9be0: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
9bf0: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
9c00: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
9c10: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
9c20: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9c30: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
9c40: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
9c50: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
9c60: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
9c70: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
9c80: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
9c90: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
9ca0: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
9cb0: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
9cc0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9cd0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
9ce0: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
9cf0: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
9d00: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
9d10: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
9d20: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9d30: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9d40: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
9d50: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
9d60: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9d70: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9d80: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9d90: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
9da0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
9db0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9dc0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9dd0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9de0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
9df0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
9e00: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
9e10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9e20: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
9e30: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
9e40: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9e50: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
9e60: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
9e70: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
9e80: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
9e90: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
9ea0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
9eb0: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
9ec0: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
9ed0: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
9ee0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
9ef0: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
9f00: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
9f10: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
9f20: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
9f30: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
9f40: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9f50: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9f60: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9f70: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
9f80: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
9f90: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9fa0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9fb0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9fc0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9fd0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9fe0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
9ff0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
a000: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
a010: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a020: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
a030: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
a040: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
a050: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
a060: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
a070: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
a080: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
a090: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
a0a0: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
a0b0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
a0c0: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
a0d0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
a0e0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
a0f0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
a100: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
a110: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
a120: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
a130: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
a140: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
a150: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
a160: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
a170: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
a180: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
a190: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
a1a0: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
a1b0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
a1c0: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
a1d0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
a1e0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
a1f0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
a200: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
a210: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
a220: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
a230: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
a240: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
a250: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
a260: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a270: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
a280: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
a290: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
a2a0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
a2b0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
a2c0: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
a2d0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
a2e0: 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72 65  er is the new re
a2f0: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
a300: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
a310: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
a320: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
a330: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
a340: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
a350: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
a360: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
a370: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
a380: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
a390: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
a3a0: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
a3b0: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
a3c0: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
a3d0: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
a3e0: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
a3f0: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
a400: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
a410: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
a420: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a430: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
a440: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a450: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
a460: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a470: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a480: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
a490: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
a4a0: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
a4b0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
a4c0: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
a4d0: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64  te ahead log and
a4e0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
a4f0: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
a500: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
a510: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
a520: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
a530: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
a540: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
a550: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
a560: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
a570: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a580: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
a590: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
a5a0: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
a5b0: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
a5c0: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
a5d0: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
a5e0: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
a5f0: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
a600: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
a610: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
a620: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
a630: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
a640: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
a650: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
a660: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
a670: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
a680: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
a690: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
a6a0: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
a6b0: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
a6c0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a6d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a6e0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a6f0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a700: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a710: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a720: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a730: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
a740: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a750: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a760: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
a770: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
a780: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a790: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a7a0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a7b0: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
a7c0: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
a7d0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a7e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a7f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a800: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a810: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a820: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
a830: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a840: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a850: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
a860: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
a870: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
a880: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
a890: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
a8a0: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
a8b0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
a8c0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
a8d0: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
a8e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
a8f0: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
a900: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a910: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a920: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a930: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
a940: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
a950: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
a960: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
a970: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
a980: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
a990: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a9a0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
a9b0: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
a9c0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a9d0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a9e0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a9f0: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
aa00: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
aa10: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
aa20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
aa30: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
aa40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa50: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
aa60: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
aa70: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
aa80: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
aa90: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
aaa0: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
aab0: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
aac0: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
aad0: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
aae0: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
aaf0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
ab00: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
ab10: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
ab20: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
ab30: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
ab40: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
ab50: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ab60: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
ab70: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ab80: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
ab90: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
aba0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
abb0: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
abc0: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
abd0: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
abe0: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
abf0: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
ac00: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
ac10: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
ac20: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
ac30: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
ac40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
ac50: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
ac60: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
ac70: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
ac80: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
ac90: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
aca0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
acb0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
acc0: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
acd0: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
ace0: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
acf0: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
ad00: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
ad10: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
ad20: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
ad30: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
ad40: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
ad50: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
ad60: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
ad70: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
ad80: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
ad90: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
ada0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
adb0: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
adc0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
add0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
ade0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
adf0: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
ae00: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
ae10: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
ae20: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ae30: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a  L_VFS_POINTER]].
ae40: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
ae50: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
ae60: 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  R] opcode finds 
ae70: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
ae80: 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56   top-level.** [V
ae90: 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20  FSes] currently 
aea0: 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61  in use.  ^(The a
aeb0: 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20  rgument X in.** 
aec0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
aed0: 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46  trol(db,SQLITE_F
aee0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
aef0: 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f  ,X) must be.** o
af00: 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33  f type "[sqlite3
af10: 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73  _vfs] **".  This
af20: 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65   opcodes will se
af30: 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69  t *X.** to a poi
af40: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d  nter to the top-
af50: 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20  level VFS.)^.** 
af60: 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20  ^When there are 
af70: 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69  multiple VFS shi
af80: 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c  ms in the stack,
af90: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e   this opcode fin
afa0: 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d  ds the.** upper-
afb0: 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a  most shim only..
afc0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
afd0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
afe0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
aff0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
b000: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
b010: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
b020: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
b030: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
b040: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
b050: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
b060: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
b070: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
b080: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
b090: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
b0a0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
b0b0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
b0c0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
b0d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b0e0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
b0f0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
b100: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
b110: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
b120: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
b130: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
b140: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
b150: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
b160: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
b170: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
b180: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
b190: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
b1a0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
b1b0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
b1c0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
b1d0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
b1e0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b1f0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
b200: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
b210: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
b220: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
b230: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
b240: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
b250: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b260: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
b270: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
b280: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
b290: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
b2a0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
b2b0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
b2c0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
b2d0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
b2e0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
b2f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b300: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b310: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
b320: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
b330: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
b340: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
b350: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
b360: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b370: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
b380: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b390: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
b3a0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
b3b0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
b3c0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
b3d0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
b3e0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
b3f0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
b400: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
b410: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72  d statement if r
b420: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20  esult string is 
b430: 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65  NULL, or that re
b440: 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20  turns a copy.** 
b450: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74  of the result st
b460: 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69  ring if the stri
b470: 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a  ng is non-NULL..
b480: 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
b490: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b4a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b4b0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
b4c0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
b4d0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
b4e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
b4f0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
b500: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
b510: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
b520: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
b530: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
b540: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
b550: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
b560: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
b570: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
b580: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b590: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b5a0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
b5b0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
b5c0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
b5d0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
b5e0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
b5f0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
b600: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
b610: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
b620: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b630: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b640: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
b650: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b660: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
b670: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
b680: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
b690: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
b6a0: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
b6b0: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
b6c0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
b6d0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
b6e0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
b6f0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
b700: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
b710: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
b720: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
b730: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
b740: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
b750: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
b760: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
b770: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
b780: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
b790: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
b7a0: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
b7b0: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
b7c0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
b7d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
b7e0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
b7f0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
b800: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
b810: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
b820: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
b830: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
b840: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
b850: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
b860: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
b870: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
b880: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
b890: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
b8a0: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
b8b0: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
b8c0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
b8d0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
b8e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b8f0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
b900: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
b910: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
b920: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b930: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
b940: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
b950: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
b960: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
b970: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
b980: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
b990: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
b9a0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
b9b0: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
b9c0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
b9d0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
b9e0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
b9f0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
ba00: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
ba10: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
ba20: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
ba30: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
ba40: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
ba50: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
ba60: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
ba70: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
ba80: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
ba90: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
baa0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
bab0: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
bac0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
bad0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bae0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
baf0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bb00: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
bb10: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
bb20: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
bb30: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
bb40: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
bb50: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
bb60: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
bb70: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
bb80: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
bb90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
bba0: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
bbb0: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
bbc0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
bbd0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
bbe0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
bbf0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
bc00: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
bc10: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
bc20: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
bc30: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
bc40: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
bc50: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
bc60: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
bc70: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
bc80: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
bc90: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
bca0: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
bcb0: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
bcc0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
bcd0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
bce0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
bcf0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
bd00: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
bd10: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
bd20: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
bd30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bd40: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
bd50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
bd60: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
bd70: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
bd80: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
bd90: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
bda0: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
bdb0: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
bdc0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
bdd0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
bde0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
bdf0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
be00: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
be10: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
be20: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
be30: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
be40: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
be50: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
be60: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
be70: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
be80: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
be90: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
bea0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
beb0: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
bec0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
bed0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
bee0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bef0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
bf00: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
bf10: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bf20: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
bf30: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
bf40: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
bf50: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
bf60: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
bf70: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
bf80: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
bf90: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
bfa0: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
bfb0: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
bfc0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
bfd0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
bfe0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
bff0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
c000: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c010: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c020: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c030: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c040: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_GET_HANDLE] o
c050: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
c060: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a  d to obtain the.
c070: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61  ** underlying na
c080: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
c090: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
c0a0: 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20   a file handle. 
c0b0: 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f   This file.** co
c0c0: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
c0d0: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
c0e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
c0f0: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
c100: 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73  le and.** writes
c110: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76   the resulting v
c120: 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a  alue there..**.*
c130: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c140: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c150: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c170: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
c180: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
c190: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
c1a0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
c1b0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
c1c0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
c1d0: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
c1e0: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
c1f0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
c200: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
c210: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
c220: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
c230: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
c240: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
c250: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
c260: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
c270: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
c280: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c290: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d  CNTL_WAL_BLOCK]]
c2a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c2b0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c2c0: 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20   is a signal to 
c2d0: 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68  the VFS layer th
c2e0: 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62  at it might.** b
c2f0: 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74  e advantageous t
c300: 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e  o block on the n
c310: 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20  ext WAL lock if 
c320: 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20  the lock is not 
c330: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61  immediately.** a
c340: 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57  vailable.  The W
c350: 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73  AL subsystem iss
c360: 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20  ues this signal 
c370: 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63  during rare.** c
c380: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20  ircumstances in 
c390: 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70  order to fix a p
c3a0: 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f  roblem with prio
c3b0: 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a  rity inversion..
c3c0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
c3d0: 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f  should <em>not</
c3e0: 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c  em> use this fil
c3f0: 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a  e-control..**.**
c400: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c410: 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20  NTL_ZIPVFS]].** 
c420: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c430: 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65  L_ZIPVFS] opcode
c440: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c450: 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20  by zipvfs only. 
c460: 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53  All other.** VFS
c470: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c480: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c490: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  or this opcode..
c4a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c4b0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a  TE_FCNTL_RBU]].*
c4c0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c4d0: 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20  NTL_RBU] opcode 
c4e0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c4f0: 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  y the special VF
c500: 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65  S used by.** the
c510: 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f   RBU extension o
c520: 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  nly.  All other 
c530: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c540: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c550: 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70  D for.** this op
c560: 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  code.  .**.** <l
c570: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c580: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c590: 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20  ITE]].** If the 
c5a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
c5b0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
c5c0: 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73  ] opcode returns
c5d0: 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e   SQLITE_OK, then
c5e0: 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73  .** the file des
c5f0: 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65  criptor is place
c600: 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69 74  d in "batch writ
c610: 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a  e mode", which.*
c620: 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73  * means all subs
c630: 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65  equent write ope
c640: 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20  rations will be 
c650: 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e  deferred and don
c660: 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20  e.** atomically 
c670: 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c  at the next [SQL
c680: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c690: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20  _ATOMIC_WRITE]. 
c6a0: 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74   Systems.** that
c6b0: 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
c6c0: 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69  batch atomic wri
c6d0: 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  tes will return 
c6e0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e  SQLITE_NOTFOUND.
c6f0: 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61  .** ^Following a
c700: 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49   successful SQLI
c710: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c720: 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20  TOMIC_WRITE and 
c730: 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20  prior to.** the 
c740: 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  closing [SQLITE_
c750: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c760: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a  MIC_WRITE] or.**
c770: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
c780: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
c790: 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69  RITE], SQLite wi
c7a0: 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46  ll make.** no VF
c7b0: 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  S interface call
c7c0: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73  s on the same [s
c7d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c  qlite3_file] fil
c7e0: 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20  e descriptor.** 
c7f0: 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73  except for calls
c800: 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d   to the xWrite m
c810: 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46  ethod and the xF
c820: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
c830: 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54  d.** with [SQLIT
c840: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
c850: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  T]..**.** <li>[[
c860: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c870: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
c880: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c890: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c8a0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63  TOMIC_WRITE] opc
c8b0: 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77  ode causes all w
c8c0: 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  rite.** operatio
c8d0: 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65  ns since the pre
c8e0: 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c  vious successful
c8f0: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51   call to .** [SQ
c900: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
c910: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74  _ATOMIC_WRITE] t
c920: 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61  o be performed a
c930: 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68  tomically..** Th
c940: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
c950: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
c960: 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  OK] if and only 
c970: 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77 65  if the writes we
c980: 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72  re.** all perfor
c990: 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  med successfully
c9a0: 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63   and have been c
c9b0: 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73  ommitted to pers
c9c0: 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a  istent storage..
c9d0: 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
c9e0: 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
c9f0: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75   it is successfu
ca00: 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  l, this file con
ca10: 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68  trol takes.** th
ca20: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
ca30: 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77  r out of batch w
ca40: 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61  rite mode so tha
ca50: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
ca60: 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74  .** write operat
ca70: 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e  ions are indepen
ca80: 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  dent..** ^SQLite
ca90: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
caa0: 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ke SQLITE_FCNTL_
cab0: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
cac0: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
cad0: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
cae0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
caf0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cb00: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a  OMIC_WRITE]..**.
cb10: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cb20: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41  FCNTL_ROLLBACK_A
cb30: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
cb40: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
cb50: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
cb60: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
cb70: 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74   causes all writ
cb80: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20  e.** operations 
cb90: 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f  since the previo
cba0: 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  us successful ca
cbb0: 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54  ll to .** [SQLIT
cbc0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cbd0: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62  OMIC_WRITE] to b
cbe0: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  e rolled back..*
cbf0: 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  * ^This file con
cc00: 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66  trol takes the f
cc10: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f  ile descriptor o
cc20: 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74  ut of batch writ
cc30: 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61  e mode.** so tha
cc40: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
cc50: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
cc60: 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e  s are independen
cc70: 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  t..** ^SQLite wi
cc80: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
cc90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
cca0: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
ccb0: 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  TE without.** a 
ccc0: 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
ccd0: 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45   call to [SQLITE
cce0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
ccf0: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 20 3c  MIC_WRITE]..** <
cd00: 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /ul>.*/.#define 
cd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
cd20: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
cd30: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
cd40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
cd50: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
cd60: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
cd70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
cd80: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
cd90: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
cda0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45  ITE_FCNTL_LAST_E
cdb0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
cdc0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
cdd0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
cde0: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
cdf0: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
ce00: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
ce10: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
ce20: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
ce30: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
ce40: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
ce50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ce60: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
ce70: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
ce80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ce90: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
cea0: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
ceb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cec0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
ced0: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
cee0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cef0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
cf00: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
cf10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cf20: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
cf30: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
cf40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cf50: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
cf60: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
cf70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cf80: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
cf90: 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e         14.#defin
cfa0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
cfb0: 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20  USYHANDLER      
cfc0: 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65        15.#define
cfd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45   SQLITE_FCNTL_TE
cfe0: 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20  MPFILENAME      
cff0: 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20       16.#define 
d000: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
d010: 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  P_SIZE          
d020: 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53      18.#define S
d030: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
d040: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
d050: 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51     19.#define SQ
d060: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
d070: 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20  OVED            
d080: 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    20.#define SQL
d090: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20  ITE_FCNTL_SYNC  
d0a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d0b0: 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   21.#define SQLI
d0c0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
d0d0: 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20  PHASETWO        
d0e0: 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  22.#define SQLIT
d0f0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
d100: 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32  T_HANDLE       2
d110: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
d120: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
d130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
d140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d150: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20  FCNTL_ZIPVFS    
d160: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a               25.
d170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d180: 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20  CNTL_RBU        
d190: 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 23              26.#
d1a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d1b0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20  NTL_VFS_POINTER 
d1c0: 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23 64             27.#d
d1d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d1e0: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
d1f0: 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 64 65  ER        28.#de
d200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d210: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
d220: 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 65 66  LE       29.#def
d230: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d240: 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 20 20  _PDB            
d250: 20 20 20 20 20 20 20 20 33 30 0a 23 64 65 66 69          30.#defi
d260: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d270: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
d280: 54 45 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e  TE     31.#defin
d290: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d2a0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
d2b0: 54 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65  TE    32.#define
d2c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f   SQLITE_FCNTL_RO
d2d0: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
d2e0: 49 54 45 20 20 33 33 0a 0a 2f 2a 20 64 65 70 72  ITE  33../* depr
d2f0: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
d300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
d310: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
d320: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
d330: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
d340: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
d350: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
d360: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
d370: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
d380: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
d390: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
d3a0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
d3b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
d3c0: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
d3d0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
d3e0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
d3f0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
d400: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
d410: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
d420: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
d430: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
d440: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
d450: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
d460: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
d470: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
d480: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
d490: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
d4a0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
d4b0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
d4c0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
d4d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
d4e0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
d4f0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
d500: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
d510: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
d520: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
d530: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
d540: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
d550: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d560: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
d570: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
d580: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
d590: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
d5a0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
d5b0: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
d5c0: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
d5d0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
d5e0: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
d5f0: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
d600: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
d610: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
d620: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
d630: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
d640: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
d650: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
d660: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
d670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
d680: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
d690: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
d6a0: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
d6b0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
d6c0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
d6d0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
d6e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
d6f0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
d700: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
d710: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
d720: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
d730: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
d740: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
d750: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
d760: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
d770: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
d780: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
d790: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
d7a0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
d7b0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
d7c0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
d7d0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
d7e0: 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69 73  VFS interface is
d7f0: 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 6e   sometimes exten
d800: 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e 65  ded by adding ne
d810: 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a  w methods onto.*
d820: 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63 68  * the end.  Each
d830: 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65 78   time such an ex
d840: 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c 20  tension occurs, 
d850: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
d860: 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d 65  ld.** is increme
d870: 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72 73  nted.  The iVers
d880: 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74 65  ion value starte
d890: 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a 2a  d out as 1 in.**
d8a0: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
d8b0: 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 65   3.5.0] on [date
d8c0: 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e 20  of:3.5.0], then 
d8d0: 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a 2a  increased to 2.*
d8e0: 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76  * with SQLite [v
d8f0: 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e  ersion 3.7.0] on
d900: 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c   [dateof:3.7.0],
d910: 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 61   and then increa
d920: 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 68  sed.** to 3 with
d930: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
d940: 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 65   3.7.6] on [date
d950: 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 69  of:3.7.6].  Addi
d960: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
d970: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
d980: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
d990: 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 74  vfs object and t
d9a0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
d9b0: 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 73  e.** may increas
d9c0: 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75 72  e again in futur
d9d0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
d9e0: 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  Lite..** Note th
d9f0: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
da00: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
da10: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
da20: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
da30: 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  nsition from.** 
da40: 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20  SQLite [version 
da50: 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 69  3.5.9] to [versi
da60: 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61  on 3.6.0] on [da
da70: 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61  teof:3.6.0].** a
da80: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
da90: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
daa0: 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  t modified..**.*
dab0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
dac0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
dad0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
dae0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
daf0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
db00: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
db10: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
db20: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
db30: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
db40: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
db50: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
db60: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
db70: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
db80: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
db90: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
dba0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
dbb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
dbc0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
dbd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
dbe0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
dbf0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
dc00: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
dc10: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
dc20: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
dc30: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
dc40: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
dc50: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
dc60: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
dc70: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
dc80: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
dc90: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
dca0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
dcb0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
dcc0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
dcd0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
dce0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
dcf0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
dd00: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
dd10: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
dd20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
dd30: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
dd40: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
dd50: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
dd60: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
dd70: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
dd80: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
dd90: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
dda0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
ddb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
ddc0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
ddd0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
dde0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
ddf0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
de00: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
de10: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
de20: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
de30: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
de40: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
de50: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
de60: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
de70: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
de80: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
de90: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
dea0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
deb0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
dec0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
ded0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
dee0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
def0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
df00: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
df10: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
df20: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
df30: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
df40: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
df50: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
df60: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
df70: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
df80: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
df90: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
dfa0: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
dfb0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
dfc0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
dfd0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
dfe0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
dff0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
e000: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
e010: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
e020: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
e030: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
e040: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
e050: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
e060: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
e070: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
e080: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
e090: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
e0a0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
e0b0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
e0c0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
e0d0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
e0e0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
e0f0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
e100: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
e110: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
e120: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
e130: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
e140: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
e150: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e160: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
e170: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
e180: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
e190: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
e1a0: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
e1b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
e1c0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
e1d0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
e1e0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
e1f0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
e200: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
e210: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
e220: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
e230: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
e240: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
e250: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
e260: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
e270: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
e280: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
e290: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
e2a0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
e2b0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
e2c0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
e2d0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
e2e0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
e2f0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
e300: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
e310: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
e320: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
e330: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
e340: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
e350: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
e360: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
e370: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
e380: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
e390: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
e3a0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
e3b0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
e3c0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
e3d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e3e0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
e3f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
e400: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
e410: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e420: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
e430: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e440: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
e450: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e460: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
e470: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
e480: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
e490: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
e4a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
e4b0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
e4c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e4d0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
e4e0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
e4f0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
e500: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
e510: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
e520: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
e530: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
e540: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
e550: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
e560: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
e570: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
e580: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
e590: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
e5a0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
e5b0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
e5c0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
e5d0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
e5e0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
e5f0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
e600: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
e610: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
e620: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
e630: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
e640: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
e650: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
e660: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
e670: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
e680: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
e690: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
e6a0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
e6b0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
e6c0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
e6d0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
e6e0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
e6f0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
e700: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
e710: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
e720: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
e730: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
e740: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
e750: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
e760: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e770: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
e780: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
e790: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
e7a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
e7b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
e7c0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
e7d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
e7e0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
e7f0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
e800: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
e810: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
e820: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
e830: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
e840: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
e850: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
e860: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
e870: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
e880: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
e890: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
e8a0: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
e8b0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
e8c0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
e8d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
e8e0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
e8f0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
e900: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
e910: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
e920: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
e930: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
e940: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
e950: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
e960: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
e970: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
e980: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
e990: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
e9a0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
e9b0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
e9c0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
e9d0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
e9e0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
e9f0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
ea00: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
ea10: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
ea20: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
ea30: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
ea40: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
ea50: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
ea60: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
ea70: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
ea80: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
ea90: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
eaa0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
eab0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
eac0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
ead0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
eae0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
eaf0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
eb00: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
eb10: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
eb20: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
eb30: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
eb40: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
eb50: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
eb60: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
eb70: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
eb80: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
eb90: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
eba0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ebb0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
ebc0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
ebd0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
ebe0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
ebf0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
ec00: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
ec10: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
ec20: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
ec30: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
ec40: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
ec50: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
ec60: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
ec70: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
ec80: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
ec90: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
eca0: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
ecb0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
ecc0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
ecd0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
ece0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
ecf0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
ed00: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
ed10: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
ed20: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
ed30: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
ed40: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
ed50: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
ed60: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
ed70: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
ed80: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
ed90: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
eda0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
edb0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
edc0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
edd0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
ede0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
edf0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
ee00: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
ee10: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
ee20: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
ee30: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
ee40: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
ee50: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
ee60: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
ee70: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
ee80: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
ee90: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
eea0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
eeb0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
eec0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
eed0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
eee0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
eef0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
ef00: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
ef10: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
ef20: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
ef30: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
ef40: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
ef50: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
ef60: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
ef70: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
ef80: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
ef90: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
efa0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
efb0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
efc0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
efd0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
efe0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
eff0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
f000: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
f010: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
f020: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
f030: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
f040: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
f050: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
f060: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
f070: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
f080: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
f090: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
f0a0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
f0b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
f0c0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
f0d0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
f0e0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
f0f0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
f100: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
f110: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
f120: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
f130: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
f140: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
f150: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
f160: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
f170: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
f180: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
f190: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
f1a0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
f1b0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
f1c0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
f1d0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
f1e0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
f1f0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
f200: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
f210: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
f220: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
f230: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
f240: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
f250: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
f260: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
f270: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
f280: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
f290: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
f2a0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
f2b0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
f2c0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
f2d0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
f2e0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
f2f0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
f300: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
f310: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
f320: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
f330: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
f340: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
f350: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
f360: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
f370: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
f380: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
f390: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
f3a0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
f3b0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
f3c0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
f3d0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
f3e0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
f3f0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
f400: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
f410: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
f420: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
f430: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
f440: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
f450: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
f460: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
f470: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
f480: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
f490: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
f4a0: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
f4b0: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
f4c0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
f4d0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
f4e0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
f4f0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
f500: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
f510: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
f520: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
f530: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
f540: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
f550: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
f560: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
f570: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
f580: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
f590: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
f5a0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
f5b0: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
f5c0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
f5d0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
f5e0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
f5f0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
f600: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
f610: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
f620: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
f630: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
f640: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
f650: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
f660: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
f670: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
f680: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
f690: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
f6a0: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
f6b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
f6c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
f6d0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
f6e0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
f6f0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
f700: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
f710: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
f720: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
f730: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
f740: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
f750: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
f760: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
f770: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
f780: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
f790: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
f7a0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
f7b0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
f7c0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
f7d0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
f7e0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
f7f0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
f800: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
f810: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
f820: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
f830: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
f840: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
f850: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
f860: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
f870: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
f880: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
f890: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
f8a0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
f8b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f8c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f8d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
f8e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
f8f0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
f900: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
f910: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
f920: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f930: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f940: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
f950: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
f960: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f970: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f980: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
f990: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
f9a0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
f9b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f9c0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
f9d0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
f9e0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
f9f0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
fa00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fa10: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
fa20: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
fa30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fa40: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
fa50: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
fa60: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
fa70: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
fa80: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
fa90: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
faa0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
fab0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fac0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
fad0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
fae0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
faf0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
fb00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
fb10: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
fb20: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
fb30: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
fb40: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
fb50: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
fb60: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
fb70: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
fb80: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
fb90: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
fba0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
fbb0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
fbc0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
fbd0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
fbe0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
fbf0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
fc00: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
fc10: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
fc20: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
fc30: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
fc40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
fc50: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
fc60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
fc70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
fc80: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
fc90: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
fca0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
fcb0: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
fcc0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
fcd0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
fce0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
fcf0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
fd00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fd10: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
fd20: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
fd30: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
fd40: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
fd50: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
fd60: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
fd70: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
fd80: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
fd90: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
fda0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
fdb0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
fdc0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
fdd0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
fde0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
fdf0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
fe00: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
fe10: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
fe20: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
fe30: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
fe40: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
fe50: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
fe60: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
fe70: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
fe80: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
fe90: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
fea0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
feb0: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
fec0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
fed0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
fee0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
fef0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
ff00: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
ff10: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
ff20: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
ff30: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
ff40: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
ff50: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
ff60: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ff70: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
ff80: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ff90: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
ffa0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ffb0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
ffc0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
ffd0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
ffe0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
fff0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
10000 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10010 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10020 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
10030 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
10040 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
10050 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
10060 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
10070 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
10080 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
10090 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
100a0 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
100b0 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
100c0 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
100d0 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
100e0 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
100f0 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
10100 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
10110 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
10120 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
10130 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
10140 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10150 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
10160 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
10170 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10180 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10190 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
101a0 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
101b0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
101c0 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
101d0 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
101e0 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
101f0 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
10200 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
10210 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
10220 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
10230 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
10240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10250 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10260 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
10270 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
10280 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
10290 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
102a0 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
102b0 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
102c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
102d0 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
102e0 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
102f0 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
10300 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
10310 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
10320 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
10330 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
10340 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
10350 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
10360 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
10370 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
10380 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
10390 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
103a0 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
103b0 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
103c0 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
103d0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
103e0 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
103f0 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10400 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10410 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
10420 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
10430 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10440 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10450 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
10460 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
10470 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
10480 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10490 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
104a0 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
104b0 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
104c0 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
104d0 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
104e0 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
104f0 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
10500 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
10510 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
10520 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
10530 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
10540 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
10550 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
10560 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
10570 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
10580 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
10590 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
105a0 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
105b0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
105c0 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
105d0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
105e0 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
105f0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
10600 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10610 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
10620 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
10630 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
10640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
10650 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
10660 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
10670 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
10680 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
10690 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
106a0 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
106b0 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
106c0 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
106d0 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
106e0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
106f0 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
10700 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
10710 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
10720 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
10730 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
10740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10750 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
10760 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
10770 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
10780 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10790 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
107a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
107b0 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
107c0 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
107d0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
107e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
107f0 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
10800 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
10810 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
10820 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
10830 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
10840 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
10850 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
10860 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
10870 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
10880 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
10890 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
108a0 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
108b0 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
108c0 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
108d0 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
108e0 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
108f0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
10900 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
10910 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
10920 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10930 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
10940 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
10950 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
10960 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
10970 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
10980 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
10990 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
109a0 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
109b0 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
109c0 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
109d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
109e0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
109f0 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
10a00 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10a10 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
10a20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
10a30 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
10a40 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
10a50 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
10a60 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
10a70 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
10a80 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
10a90 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
10aa0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10ab0 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
10ac0 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
10ad0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
10ae0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
10af0 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
10b00 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
10b10 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
10b20 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
10b30 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
10b40 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10b50 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
10b60 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
10b70 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
10b80 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
10b90 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
10ba0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
10bb0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
10bc0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10bd0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
10be0 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
10bf0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10c00 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
10c10 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10c20 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
10c30 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
10c40 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
10c50 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
10c60 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
10c70 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
10c80 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
10c90 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
10ca0 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
10cb0 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
10cc0 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
10cd0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
10ce0 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
10cf0 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
10d00 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
10d10 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
10d20 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
10d30 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
10d40 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
10d50 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
10d60 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
10d70 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
10d80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
10d90 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
10da0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
10db0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10dc0 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
10dd0 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
10de0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10df0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
10e00 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
10e10 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
10e20 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
10e30 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
10e40 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
10e50 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
10e60 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
10e70 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
10e80 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
10e90 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
10ea0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10eb0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
10ec0 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
10ed0 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
10ee0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
10ef0 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
10f00 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
10f10 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
10f20 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
10f30 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10f40 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
10f50 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
10f60 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
10f70 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
10f80 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
10f90 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
10fa0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
10fb0 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
10fc0 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
10fd0 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
10fe0 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
10ff0 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
11000 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
11010 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
11020 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11030 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
11040 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
11050 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
11060 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
11070 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
11080 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
11090 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
110a0 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
110b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
110c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
110d0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
110e0 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
110f0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
11100 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11110 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
11120 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
11130 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
11140 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
11150 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
11160 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11170 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
11180 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
11190 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
111a0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
111b0 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
111c0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
111d0 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
111e0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
111f0 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
11200 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
11210 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11220 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
11230 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
11240 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
11250 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
11260 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
11270 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
11280 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
11290 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
112a0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
112b0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
112c0 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
112d0 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
112e0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
112f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
11300 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
11310 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
11320 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
11330 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
11340 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
11350 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
11360 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
11370 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
11380 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
11390 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
113a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
113b0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
113c0 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
113d0 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
113e0 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
113f0 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
11400 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
11410 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
11420 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11430 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
11440 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
11450 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
11460 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
11470 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
11480 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
11490 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
114a0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
114b0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
114c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
114d0 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
114e0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
114f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
11500 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
11510 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
11520 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
11530 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11540 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
11550 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
11560 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
11570 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
11580 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
11590 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
115a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
115b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
115c0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
115d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
115e0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
115f0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
11600 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
11610 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
11620 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
11630 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
11640 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
11650 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
11660 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
11670 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
11680 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
11690 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
116a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
116b0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
116c0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
116d0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
116e0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
116f0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
11700 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
11710 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11720 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
11730 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
11740 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
11750 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
11760 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
11770 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
11780 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
11790 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
117a0 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
117b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
117c0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
117d0 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
117e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
117f0 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
11800 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11810 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
11820 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
11830 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
11840 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11850 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
11860 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
11870 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11880 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
11890 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
118a0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
118b0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
118c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
118d0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
118e0 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
118f0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
11900 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
11910 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
11920 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
11930 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
11940 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
11950 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
11960 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
11970 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
11980 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
11990 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
119a0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
119b0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
119c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
119d0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
119e0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
119f0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
11a00 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
11a10 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
11a20 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
11a30 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
11a40 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
11a50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11a60 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
11a70 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
11a80 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
11a90 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11aa0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
11ab0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
11ac0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
11ad0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
11ae0 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
11af0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
11b00 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
11b10 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
11b20 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
11b30 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
11b40 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
11b50 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
11b60 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
11b70 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
11b80 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
11b90 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
11ba0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
11bb0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
11bc0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
11bd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
11be0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
11bf0 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
11c00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11c10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
11c20 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
11c30 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
11c40 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
11c50 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
11c60 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
11c70 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
11c80 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
11c90 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
11ca0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
11cb0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
11cc0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11cd0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
11ce0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
11cf0 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
11d00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
11d10 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
11d20 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
11d30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
11d40 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
11d50 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
11d60 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
11d70 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
11d80 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
11d90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
11da0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
11db0 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
11dc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
11dd0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
11de0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
11df0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11e00 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
11e10 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
11e20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
11e30 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
11e40 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
11e50 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
11e60 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
11e70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11e80 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
11e90 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
11ea0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11eb0 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
11ec0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
11ed0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
11ee0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
11ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
11f00 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
11f10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
11f20 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
11f30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
11f40 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
11f50 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
11f60 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
11f70 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
11f80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
11f90 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
11fa0 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
11fb0 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
11fc0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
11fd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11fe0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
11ff0 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
12000 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
12010 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
12020 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
12030 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
12040 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
12050 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
12060 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
12070 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
12080 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
12090 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
120a0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
120b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
120c0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
120d0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
120e0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
120f0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
12100 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
12110 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12120 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
12130 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
12140 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
12150 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
12160 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12170 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
12180 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
12190 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
121a0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
121b0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
121c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
121d0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
121e0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
121f0 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
12200 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
12210 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
12220 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
12230 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12240 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
12250 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12260 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
12270 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
12280 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12290 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
122a0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
122b0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
122c0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
122d0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
122e0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
122f0 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
12300 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
12310 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
12320 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
12330 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
12340 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
12350 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
12360 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
12370 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
12380 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
12390 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
123a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
123b0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
123c0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
123d0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
123e0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
123f0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
12400 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
12410 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
12420 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
12430 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
12440 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
12450 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
12460 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12470 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
12480 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
12490 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
124a0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
124b0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
124c0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
124d0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
124e0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
124f0 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
12500 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
12510 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
12520 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
12530 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
12540 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
12550 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
12560 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
12570 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
12580 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
12590 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
125a0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
125b0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
125c0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
125d0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
125e0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
125f0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
12600 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
12610 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12620 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
12630 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
12640 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
12650 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
12660 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
12670 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
12680 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
12690 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
126a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
126b0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
126c0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
126d0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
126e0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
126f0 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
12700 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
12710 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
12720 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
12730 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
12740 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
12750 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
12760 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
12770 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
12780 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12790 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
127a0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
127b0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
127c0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
127d0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
127e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
127f0 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
12800 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
12810 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
12820 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12830 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
12840 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
12850 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
12860 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
12870 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
12880 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
12890 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
128a0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
128b0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
128c0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
128d0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
128e0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
128f0 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
12900 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
12910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
12920 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
12930 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
12940 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
12950 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
12960 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
12970 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
12980 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
12990 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
129a0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
129b0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
129c0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
129d0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
129e0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
129f0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
12a00 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
12a10 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
12a20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
12a30 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
12a40 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
12a50 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
12a60 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
12a70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
12a80 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
12a90 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
12aa0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
12ab0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
12ac0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
12ad0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
12ae0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
12af0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
12b00 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
12b10 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
12b20 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
12b30 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
12b40 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
12b50 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
12b60 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
12b70 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
12b80 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
12b90 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
12ba0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
12bb0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
12bc0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
12bd0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
12be0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
12bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12c00 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
12c10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
12c20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
12c30 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
12c40 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
12c50 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
12c60 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
12c70 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
12c80 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
12c90 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
12ca0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
12cb0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
12cc0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
12cd0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
12ce0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
12cf0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
12d00 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
12d10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
12d20 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
12d30 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
12d40 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
12d50 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
12d60 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
12d70 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
12d80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
12d90 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
12da0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12db0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
12dc0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
12dd0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
12de0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
12df0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
12e00 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
12e10 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
12e20 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
12e30 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
12e40 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
12e50 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
12e60 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
12e70 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
12e80 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12e90 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
12ea0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
12eb0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
12ec0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
12ed0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
12ee0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
12ef0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
12f00 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
12f10 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
12f20 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
12f30 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
12f40 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
12f50 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
12f60 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
12f70 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
12f80 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
12f90 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
12fa0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12fb0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
12fc0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
12fd0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
12fe0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
12ff0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
13000 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
13010 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
13020 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
13030 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
13040 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
13050 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
13060 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
13070 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
13080 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13090 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
130a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
130b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
130c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
130d0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
130e0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
130f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13100 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
13110 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
13120 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
13130 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
13140 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13150 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
13160 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
13170 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
13180 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
13190 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
131a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
131b0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
131c0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
131d0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
131e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
131f0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
13200 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
13210 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
13220 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
13230 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
13240 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13250 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
13260 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
13270 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13280 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
13290 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
132a0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
132b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
132c0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
132d0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
132e0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
132f0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13300 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13310 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
13320 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
13330 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
13340 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
13350 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
13360 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
13370 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
13380 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
13390 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
133a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
133b0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
133c0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
133d0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
133e0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
133f0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13400 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
13410 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
13420 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
13430 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
13440 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
13450 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
13460 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
13470 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
13480 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
13490 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
134a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
134b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
134c0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
134d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
134e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
134f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13500 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
13510 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13520 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
13530 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
13540 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
13550 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
13560 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
13570 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
13580 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
13590 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
135a0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
135b0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
135c0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
135d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
135e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
135f0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
13600 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
13610 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
13620 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
13630 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
13640 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
13650 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13660 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
13670 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
13680 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
13690 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
136a0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
136b0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
136c0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
136d0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
136e0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
136f0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
13700 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
13710 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13720 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
13730 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
13740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13750 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13760 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13770 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13780 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13790 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
137a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
137b0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
137c0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
137d0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
137e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
137f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
13800 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13810 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
13820 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
13830 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
13840 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13850 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
13860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13870 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
13880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
13890 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
138a0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
138b0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
138c0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
138d0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
138e0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
138f0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
13900 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
13910 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
13920 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
13930 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
13940 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
13950 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
13960 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13970 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
13980 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
13990 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
139a0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
139b0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
139c0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
139d0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
139e0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
139f0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
13a00 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
13a10 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
13a20 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
13a30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
13a40 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
13a50 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
13a60 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
13a70 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
13a80 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
13a90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13aa0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
13ab0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
13ac0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
13ad0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
13ae0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
13af0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
13b00 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13b10 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
13b20 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
13b30 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
13b40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13b50 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
13b60 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
13b70 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
13b80 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
13b90 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
13ba0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
13bb0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
13bc0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
13bd0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
13be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
13bf0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
13c00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
13c10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13c20 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13c30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13c40 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
13c50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13c60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13c70 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
13c80 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13c90 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
13ca0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
13cb0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
13cc0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13cd0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
13ce0 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
13cf0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
13d00 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
13d10 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
13d20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
13d30 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
13d40 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
13d50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
13d60 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
13d70 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
13d80 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
13d90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
13da0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
13db0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13dc0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
13dd0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
13de0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
13df0 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
13e00 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
13e10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13e20 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
13e30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13e40 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
13e50 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13e60 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13e70 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
13e80 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13e90 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
13ea0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13eb0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
13ec0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13ed0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13ee0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
13ef0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
13f00 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13f10 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13f20 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13f30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13f40 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
13f50 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13f60 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13f70 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
13f80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13f90 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
13fa0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
13fb0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
13fc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13fd0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
13fe0 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
13ff0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
14000 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14010 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
14020 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  LL_MALLOC]] <dt>
14030 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
14040 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  ALL_MALLOC</dt>.
14050 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
14060 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
14070 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  _MALLOC option t
14080 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
14090 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20  ment of.** type 
140a0 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
140b0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
140c0 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f  hich if true pro
140d0 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a  vides a hint to.
140e0 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  ** SQLite that i
140f0 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c  t should avoid l
14100 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  arge memory allo
14110 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69  cations if possi
14120 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ble..** SQLite w
14130 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69  ill run faster i
14140 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20  f it is free to 
14150 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72  make large memor
14160 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a  y allocations,.*
14170 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69  * but some appli
14180 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65  cation might pre
14190 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65  fer to run slowe
141a0 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f  r in exchange fo
141b0 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  r.** guarantees 
141c0 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61  about memory fra
141d0 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  gmentation that 
141e0 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20  are possible if 
141f0 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  large.** allocat
14200 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64  ions are avoided
14210 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
14220 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a  normally off..**
14230 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
14250 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
14260 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14270 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
14280 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
14290 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
142a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
142b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
142c0 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
142d0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
142e0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
142f0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
14300 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
14310 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
14320 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14330 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
14340 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14350 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
14360 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
14370 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
14380 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
14390 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
143a0 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
143b0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
143c0 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
143d0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
143e0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
143f0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
14400 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
14410 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
14420 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
14430 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
14440 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
14450 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
14460 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
14470 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
14480 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
14490 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
144a0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
144b0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
144c0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
144d0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
144e0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
144f0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
14500 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
14510 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14520 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
14530 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14540 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
14550 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
14560 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
14570 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ption is no long
14580 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64  er used..** </dd
14590 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
145a0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
145b0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
145c0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
145d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
145e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
145f0 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
14600 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d   specifies a mem
14610 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74  ory pool.** that
14620 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
14630 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
14640 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
14650 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
14660 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
14670 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
14680 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
14690 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e  on option is a n
146a0 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69  o-op if an appli
146b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
146c0 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
146d0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
146e0 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
146f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14700 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72  ACHE2]..** ^Ther
14710 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
14720 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
14730 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14740 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  : A pointer to.*
14750 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  * 8-byte aligned
14760 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20   memory (pMem), 
14770 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
14780 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
14790 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
147a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68  e number of cach
147b0 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20  e lines (N)..** 
147c0 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
147d0 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
147e0 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
147f0 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
14800 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
14810 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
14820 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
14830 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
14840 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
14850 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
14860 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
14870 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
14880 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
14890 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
148a0 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54  ned using [SQLIT
148b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
148c0 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69  HDRSZ]..** ^It i
148d0 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
148e0 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
148f0 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
14900 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
14910 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
14920 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
14930 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75  The pMem.** argu
14940 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74  ment must be eit
14950 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
14960 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  er or a pointer 
14970 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
14980 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66  aligned block of
14990 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65   memory of at le
149a0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20  ast sz*N bytes, 
149b0 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62  otherwise.** sub
149c0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
149d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
149e0 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20  * ^When pMem is 
149f0 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
14a00 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20   will strive to 
14a10 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
14a20 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61  rovided.** to sa
14a30 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65  tisfy page cache
14a40 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20   needs, falling 
14a50 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33  back to [sqlite3
14a60 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a  _malloc()] if.**
14a70 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69   a page cache li
14a80 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61  ne is larger tha
14a90 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66  n sz bytes or if
14aa0 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d   all of the pMem
14ab0 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78   buffer.** is ex
14ac0 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20  hausted..** ^If 
14ad0 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64  pMem is NULL and
14ae0 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20   N is non-zero, 
14af0 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61  then each databa
14b00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
14b10 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c   does an initial
14b20 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e   bulk allocation
14b30 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
14b40 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b  memory.** from [
14b50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14b60 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72  ] sufficient for
14b70 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69   N cache lines i
14b80 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20  f N is positive 
14b90 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e  or.** of -1024*N
14ba0 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e   bytes if N is n
14bb0 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61  egative, . ^If a
14bc0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
14bd0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
14be0 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
14bf0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
14c00 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a   by the initial.
14c10 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ** allocation, t
14c20 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20  hen SQLite goes 
14c30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
14c40 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79  oc()] separately
14c50 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64   for each.** add
14c60 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69  itional cache li
14c70 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ne. </dd>.**.** 
14c80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14c90 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
14ca0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
14cb0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14cc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14cd0 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
14ce0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
14cf0 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
14d00 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
14d10 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
14d20 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
14d30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
14d40 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
14d50 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
14d60 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
14d70 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
14d80 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14d90 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
14da0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
14db0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
14dc0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
14dd0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
14de0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
14df0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
14e00 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
14e10 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
14e20 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
14e30 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
14e40 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
14e50 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
14e60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14e70 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
14e80 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
14e90 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
14ea0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
14eb0 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
14ec0 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
14ed0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
14ee0 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
14ef0 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
14f00 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14f10 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
14f20 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
14f30 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
14f40 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
14f50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14f60 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
14f70 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
14f80 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
14f90 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
14fa0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
14fb0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
14fc0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
14fd0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
14fe0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
14ff0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
15000 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
15010 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
15020 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
15030 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
15040 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
15050 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
15060 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
15070 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
15080 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
15090 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
150a0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
150b0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
150c0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
150d0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
150e0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
150f0 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
15100 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
15110 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
15120 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
15130 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
15140 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
15150 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
15160 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15170 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
15180 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
15190 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
151a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
151b0 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
151c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
151d0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
151e0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
151f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
15200 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15210 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15220 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
15230 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
15240 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
15250 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
15260 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
15270 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
15280 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
15290 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
152a0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
152b0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
152c0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
152d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
152e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
152f0 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
15300 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
15310 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
15320 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
15330 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15340 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15350 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15360 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15370 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
15380 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
15390 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
153a0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
153b0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
153c0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
153d0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
153e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
153f0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
15400 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
15410 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15420 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15430 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
15440 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15460 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
15470 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15480 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
15490 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
154a0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
154b0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
154c0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
154d0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
154e0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
154f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15500 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
15510 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
15520 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
15530 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
15540 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
15550 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
15560 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
15570 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
15580 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
15590 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
155a0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
155b0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
155c0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
155d0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
155e0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
155f0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
15600 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
15610 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
15620 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
15630 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
15640 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
15650 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
15660 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
15670 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
15680 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15690 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
156a0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
156b0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
156c0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
156d0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
156e0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
156f0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
15700 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15710 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
15720 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
15730 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
15740 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
15750 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15760 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
15770 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
15780 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
15790 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
157a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
157b0 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
157c0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
157d0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
157e0 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
157f0 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
15800 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
15810 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
15820 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
15830 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15840 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
15850 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
15860 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
15870 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
15880 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
15890 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
158a0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
158b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
158c0 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
158d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
158e0 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
158f0 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
15900 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
15910 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15920 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
15930 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
15940 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
15950 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
15960 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
15970 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15980 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
15990 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
159a0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
159b0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
159c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
159d0 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
159e0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
159f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15a00 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
15a10 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15a20 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
15a30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15a40 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15a50 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
15a60 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
15a70 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
15a80 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
15a90 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
15aa0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
15ab0 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
15ac0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
15ad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
15ae0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
15af0 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
15b00 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15b10 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
15b20 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
15b30 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
15b40 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
15b50 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15b60 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
15b70 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15b80 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
15b90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15ba0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15bb0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
15bc0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
15bd0 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
15be0 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
15bf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
15c00 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
15c10 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
15c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15c30 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
15c40 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
15c50 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
15c60 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
15c70 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
15c80 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
15c90 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
15ca0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
15cb0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15cc0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
15cd0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
15ce0 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
15cf0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
15d00 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
15d10 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
15d20 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
15d30 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
15d40 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
15d50 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
15d60 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
15d70 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
15d80 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
15d90 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
15da0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
15db0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
15dc0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
15dd0 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
15de0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
15df0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
15e00 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
15e10 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
15e20 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
15e30 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15e40 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15e50 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
15e60 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
15e70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15e80 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
15e90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
15ea0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
15eb0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
15ec0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
15ed0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
15ee0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
15ef0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
15f00 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
15f10 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15f20 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
15f30 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
15f40 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
15f50 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
15f60 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
15f70 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
15f80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
15f90 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
15fa0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
15fb0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
15fc0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
15fd0 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
15fe0 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
15ff0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
16000 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
16010 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
16020 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
16030 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
16040 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
16050 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
16060 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
16070 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
16080 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
16090 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
160a0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
160b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
160c0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
160d0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
160e0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
160f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16100 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
16110 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16120 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
16130 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16140 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
16150 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16160 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
16170 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
16180 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
16190 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
161a0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
161b0 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
161c0 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
161d0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
161e0 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
161f0 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
16200 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
16210 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
16220 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
16230 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
16240 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
16250 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
16260 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
16270 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
16280 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
16290 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
162a0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
162b0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
162c0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
162d0 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
162e0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
162f0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
16300 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
16310 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
16320 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
16330 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
16340 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
16350 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
16360 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
16370 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
16380 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
16390 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
163a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
163b0 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
163c0 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
163d0 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
163e0 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
163f0 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
16400 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
16410 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
16420 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
16430 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
16440 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
16450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
16460 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
16470 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16480 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
16490 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
164a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
164b0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
164c0 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
164d0 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
164e0 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
164f0 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
16500 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
16510 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
16520 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
16530 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
16540 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
16550 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
16560 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
16570 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
16580 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
16590 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
165a0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
165b0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
165c0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
165d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
165e0 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
165f0 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
16600 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
16610 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
16620 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
16630 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
16640 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
16650 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
16660 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
16670 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
16680 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
16690 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
166a0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
166b0 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
166c0 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
166d0 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
166e0 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
166f0 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
16700 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
16710 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
16720 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
16730 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
16740 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
16750 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
16760 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
16770 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16780 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
16790 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
167a0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
167b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
167c0 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
167d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
167e0 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
167f0 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
16800 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
16810 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
16820 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
16830 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
16840 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
16850 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
16860 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
16870 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
16880 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16890 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
168a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
168b0 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
168c0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
168d0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
168e0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
168f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
16900 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
16910 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
16920 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
16930 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
16940 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
16950 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
16960 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
16970 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
16980 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
16990 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
169a0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
169b0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
169c0 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
169d0 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
169e0 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
169f0 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
16a00 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
16a10 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
16a20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
16a30 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
16a40 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
16a50 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
16a60 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
16a70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16a80 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
16a90 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
16aa0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
16ab0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
16ac0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
16ad0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
16ae0 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
16af0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
16b00 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
16b10 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
16b20 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
16b30 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
16b40 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
16b50 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
16b60 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
16b70 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
16b80 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
16b90 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
16ba0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
16bb0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
16bc0 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
16bd0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
16be0 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
16bf0 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
16c00 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
16c10 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
16c20 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
16c30 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
16c40 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
16c50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
16c60 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
16c70 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
16c80 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
16c90 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
16ca0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
16cb0 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
16cc0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16cd0 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
16ce0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16cf0 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
16d00 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
16d10 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
16d20 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
16d30 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
16d40 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
16d50 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
16d60 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
16d70 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
16d80 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
16d90 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
16da0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
16db0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
16dc0 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
16dd0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
16de0 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
16df0 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
16e00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16e10 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
16e20 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
16e30 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
16e40 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
16e50 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
16e60 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
16e70 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
16e80 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
16e90 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
16ea0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
16eb0 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
16ec0 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
16ed0 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
16ee0 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
16ef0 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
16f00 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
16f10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
16f20 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
16f30 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16f40 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
16f50 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
16f60 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
16f70 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
16f80 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
16f90 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
16fa0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
16fb0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
16fc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16fd0 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
16fe0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16ff0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17000 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17010 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17020 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
17030 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
17040 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
17050 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
17060 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
17070 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
17080 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
17090 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
170a0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
170b0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
170c0 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
170d0 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
170e0 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
170f0 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
17100 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
17110 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
17120 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
17130 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
17140 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
17150 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17160 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
17170 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17180 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
17190 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
171a0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
171b0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
171c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
171d0 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
171e0 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
171f0 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
17200 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
17210 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
17220 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
17230 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
17240 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
17250 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
17260 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
17270 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
17280 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
17290 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
172a0 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
172b0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
172c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
172d0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
172e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
172f0 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
17300 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17310 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
17320 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17330 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
17340 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
17350 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
17360 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
17370 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
17380 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
17390 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
173a0 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
173b0 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
173c0 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
173d0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
173e0 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
173f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17400 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
17410 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
17420 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
17430 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
17440 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
17450 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
17460 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
17470 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
17480 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
17490 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
174a0 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
174b0 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
174c0 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
174d0 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
174e0 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
174f0 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
17500 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
17510 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  lue..**.** [[SQL
17520 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17530 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c  RNL_SPILL]].** <
17540 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17550 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a  _STMTJRNL_SPILL.
17560 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
17570 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
17580 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20  NL_SPILL option 
17590 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
175a0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
175b0 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73  * becomes the [s
175c0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
175d0 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20  ] spill-to-disk 
175e0 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20  threshold.  .** 
175f0 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [Statement journ
17600 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e  als] are held in
17610 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68   memory until th
17620 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74  eir size (in byt
17630 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74  es).** exceeds t
17640 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61  his threshold, a
17650 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68  t which point th
17660 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74  ey are written t
17670 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66  o disk..** Or if
17680 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69   the threshold i
17690 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20  s -1, statement 
176a0 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77  journals are alw
176b0 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c  ays held.** excl
176c0 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72  usively in memor
176d0 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79  y..** Since many
176e0 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
176f0 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65  als never become
17700 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20   large, setting 
17710 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72  the spill.** thr
17720 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75  eshold to a valu
17730 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20  e such as 64KiB 
17740 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75  can greatly redu
17750 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ce the amount of
17760 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64  .** I/O required
17770 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74   to support stat
17780 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a  ement rollback..
17790 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
177a0 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65  alue for this se
177b0 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c  tting is control
177c0 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  led by the.** [S
177d0 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53  QLITE_STMTJRNL_S
177e0 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  PILL] compile-ti
177f0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f  me option..** </
17800 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
17810 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
17820 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
17830 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
17840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
17850 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
17860 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
17870 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17880 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
17890 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
178a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
178b0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
178c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
178d0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
178e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
178f0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
17900 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
17910 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
17920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17930 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
17940 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65    6  /* No longe
17950 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
17960 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17970 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
17980 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
17990 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
179a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
179b0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
179c0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
179d0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
179e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
179f0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
17a00 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
17a10 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
17a20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
17a30 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
17a40 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
17a50 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
17a60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17a70 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
17a80 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
17a90 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
17aa0 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
17ab0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
17ac0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
17ad0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
17ae0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
17af0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17b00 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
17b10 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
17b20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17b30 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
17b40 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
17b50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17b60 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
17b70 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
17b80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17b90 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
17ba0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
17bb0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
17bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
17bd0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
17be0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
17bf0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17c00 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
17c10 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
17c20 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
17c30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17c40 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
17c50 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
17c60 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
17c70 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17c80 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
17c90 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
17ca0 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
17cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17cc0 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
17cd0 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
17ce0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
17cf0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17d00 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
17d10 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
17d20 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
17d30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17d40 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17d50 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
17d60 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
17d70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17d80 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17d90 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
17da0 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
17db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17dc0 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
17dd0 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
17de0 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
17df0 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  a */.#define SQL
17e00 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17e10 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32  RNL_SPILL      2
17e20 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  6  /* int nByte 
17e30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17e40 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
17e50 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20  ALLOC        27 
17e60 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 0a   /* boolean */..
17e70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17e80 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
17e90 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
17ea0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
17eb0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
17ec0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
17ed0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
17ee0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17ef0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
17f00 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
17f10 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
17f20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
17f30 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17f40 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
17f50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17f60 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
17f70 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17f80 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
17f90 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
17fa0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17fb0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
17fc0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
17fd0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
17fe0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
17ff0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
18000 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
18010 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
18020 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
18030 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
18040 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
18050 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
18060 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
18070 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
18080 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
18090 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
180a0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
180b0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
180c0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
180d0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
180e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
180f0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
18100 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18110 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
18120 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
18130 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
18140 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
18150 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
18160 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
18170 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
18180 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18190 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
181a0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
181b0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
181c0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
181d0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
181e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
181f0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
18200 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
18210 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
18220 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
18230 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
18240 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18250 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
18260 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
18270 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
18280 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
18290 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
182a0 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
182b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
182c0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
182d0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
182e0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
182f0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
18300 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
18310 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
18320 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
18330 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
18340 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
18350 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18360 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
18370 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
18380 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
18390 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
183a0 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
183b0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
183c0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
183d0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
183e0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
183f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
18400 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
18410 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
18420 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
18430 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
18440 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
18450 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
18460 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
18470 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
18480 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
18490 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
184a0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
184b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
184c0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
184d0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
184e0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
184f0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
18500 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
18510 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
18520 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
18530 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
18540 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
18550 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
18560 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
18570 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
18580 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
18590 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
185a0 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
185b0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
185c0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
185d0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
185e0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
185f0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
18600 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
18610 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
18620 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
18630 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
18640 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18650 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
18660 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
18670 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
18680 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
18690 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
186a0 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
186b0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
186c0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
186d0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
186e0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
186f0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
18700 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
18710 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
18720 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
18730 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
18740 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
18750 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
18760 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
18770 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
18780 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
18790 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
187a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
187b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
187c0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
187d0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
187e0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
187f0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
18800 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
18810 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
18820 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
18830 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18840 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
18850 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
18860 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
18870 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
18880 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
18890 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
188a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
188b0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
188c0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
188d0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
188e0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
188f0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
18900 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
18910 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
18920 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18930 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18940 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18950 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18960 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
18970 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
18980 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
18990 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
189a0 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
189b0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
189c0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
189d0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
189e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
189f0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
18a00 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
18a10 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
18a20 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
18a30 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
18a40 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
18a50 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18a60 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
18a70 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18a80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18a90 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
18aa0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
18ab0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
18ac0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
18ad0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
18ae0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
18af0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18b00 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
18b10 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a  _TOKENIZER</dt>.
18b20 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
18b30 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18b40 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18b50 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65  e the two-argume
18b60 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  nt.** version of
18b70 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e   the [fts3_token
18b80 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
18b90 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
18ba0 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
18bb0 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
18bc0 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
18bd0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
18be0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18bf0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18c00 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
18c10 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
18c20 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
18c30 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
18c40 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
18c50 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18c60 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
18c70 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
18c80 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
18c90 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
18ca0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18cb0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18cc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18cd0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18ce0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18cf0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18d00 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
18d10 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
18d20 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
18d30 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
18d40 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18d50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18d60 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
18d70 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
18d80 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18d90 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18da0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18db0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18dc0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18dd0 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
18de0 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ON</dt>.** <dd> 
18df0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18e00 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
18e10 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73  r disable the [s
18e20 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18e30 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65  nsion()].** inte
18e40 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e  rface independen
18e50 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64  tly of the [load
18e60 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51  _extension()] SQ
18e70 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  L function..** T
18e80 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
18e90 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
18ea0 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73  n()] API enables
18eb0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74   or disables bot
18ec0 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b  h the.** C-API [
18ed0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
18ee0 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68  ension()] and th
18ef0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b  e SQL function [
18f00 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18f10 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
18f20 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18f30 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18f40 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73  ** When the firs
18f50 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
18f60 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18f70 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65  1, then only the
18f80 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61   C-API is.** ena
18f90 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  bled and the SQL
18fa0 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e   function remain
18fb0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20  s disabled.  If 
18fc0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18fd0 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e  nt to.** this in
18fe0 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68  terface is 0, th
18ff0 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50  en both the C-AP
19000 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  I and the SQL fu
19010 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62  nction are disab
19020 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  led..** If the f
19030 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
19040 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61   -1, then no cha
19050 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f  nges are made to
19060 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72   state of either
19070 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72   the.** C-API or
19080 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
19090 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  n..** The second
190a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
190b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
190c0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
190d0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
190e0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
190f0 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74  e whether [sqlit
19100 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
19110 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  n()] interface.*
19120 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  * is disabled or
19130 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69   enabled followi
19140 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19150 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19160 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20  ter may.** be a 
19170 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
19180 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
19190 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
191a0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
191b0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
191c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
191d0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c  NFIG_MAINDBNAME<
191e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
191f0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
19200 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
19210 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69  name of the "mai
19220 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73  n" database.** s
19230 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c  chema.  ^The sol
19240 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
19250 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e  pointer to a con
19260 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e  stant UTF8 strin
19270 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  g.** which will 
19280 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73  become the new s
19290 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c  chema name in pl
192a0 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20  ace of "main".  
192b0 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20  ^SQLite.** does 
192c0 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  not make a copy 
192d0 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20  of the new main 
192e0 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69  schema name stri
192f0 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69  ng, so the appli
19300 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
19310 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
19320 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
19330 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49  nto this DBCONFI
19340 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68  G option is unch
19350 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61  anged.** until a
19360 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73  fter the databas
19370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
19380 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ses..** </dd>.**
19390 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
193a0 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
193b0 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
193c0 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
193d0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
193e0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
193f0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
19400 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
19410 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
19420 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
19430 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
19440 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
19450 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
19460 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
19470 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
19480 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
19490 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
194a0 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
194b0 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
194c0 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
194d0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
194e0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
194f0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
19500 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19510 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
19520 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
19530 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e  s an integer - n
19540 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  on-zero to disab
19550 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
19560 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
19570 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
19580 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
19590 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
195a0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
195b0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
195c0 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
195d0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
195e0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
195f0 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
19600 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
19610 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
19620 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
19630 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
19640 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
19650 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
19660 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
19670 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74  _ENABLE_QPSG</dt
19680 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  >.** <dd>^(The S
19690 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
196a0 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f  NABLE_QPSG optio
196b0 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
196c0 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68  eactivates.** th
196d0 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  e [query planner
196e0 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61   stability guara
196f0 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57  ntee] (QPSG).  W
19700 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20  hen the QPSG is 
19710 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e  active,.** a sin
19720 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74  gle SQL query st
19730 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77  atement will alw
19740 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
19750 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72   algorithm regar
19760 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75  dless.** of valu
19770 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  es of [bound par
19780 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20  ameters].)^ The 
19790 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f  QPSG disables so
197a0 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  me query optimiz
197b0 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c  ations.** that l
197c0 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65  ook at the value
197d0 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d  s of bound param
197e0 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e  eters, which can
197f0 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69   make some queri
19800 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42  es.** slower.  B
19810 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20  ut the QPSG has 
19820 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66  the advantage of
19830 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c   more predictabl
19840 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74  e behavior.  Wit
19850 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63  h.** the QPSG ac
19860 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c  tive, SQLite wil
19870 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
19880 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e   same query plan
19890 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73   in the field as
198a0 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72  .** was used dur
198b0 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74  ing testing in t
198c0 68 65 20 6c 61 62 2e 0a 2a 2a 20 3c 2f 64 64 3e  he lab..** </dd>
198d0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
198e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
198f0 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41  BCONFIG_MAINDBNA
19900 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31 30  ME            10
19910 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72  00 /* const char
19920 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19930 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
19940 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20  KASIDE          
19950 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a     1001 /* void*
19960 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
19970 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19980 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
19990 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f            1002 /
199a0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
199b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
199c0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
199d0 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33  GGER        1003
199e0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
199f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19a00 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
19a10 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30  TS3_TOKENIZER 10
19a20 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  04 /* int int* *
19a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19a40 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19a50 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
19a60 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1005 /* int int*
19a70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19a80 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
19a90 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20  KPT_ON_CLOSE    
19aa0 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e    1006 /* int in
19ab0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
19ac0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19ad0 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20 20 20  ABLE_QPSG       
19ae0 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e 74 20      1007 /* int 
19af0 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
19b00 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
19b10 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
19b20 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
19b30 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
19b40 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
19b50 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
19b60 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
19b70 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
19b80 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
19b90 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
19ba0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
19bb0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
19bc0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
19bd0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
19be0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
19bf0 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
19c00 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
19c10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
19c20 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
19c30 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
19c40 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
19c50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
19c60 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
19c70 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19c80 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  e3.**.** ^Each e
19c90 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
19ca0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
19cb0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
19cc0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
19cd0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
19ce0 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
19cf0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
19d00 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
19d10 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
19d20 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
19d30 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
19d40 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
19d50 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
19d60 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
19d70 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
19d80 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
19d90 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
19da0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
19db0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
19dc0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
19dd0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
19de0 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
19df0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
19e00 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
19e10 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
19e20 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
19e30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19e40 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19e50 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 75  d(D) interface u
19e60 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  sually returns t
19e70 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a  he [rowid] of.**
19e80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
19e90 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
19ea0 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
19eb0 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
19ec0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
19ed0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19ee0 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73  tion D. ^Inserts
19ef0 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
19f00 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
19f10 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64   not.** recorded
19f20 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  . ^If no success
19f30 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
19f40 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20  to rowid tables 
19f50 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
19f60 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61  ed .** on the da
19f70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19f80 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  n D, then sqlite
19f90 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19fa0 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a  wid(D) returns .
19fb0 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41  ** zero..**.** A
19fc0 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20  s well as being 
19fd0 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  set automaticall
19fe0 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e  y as rows are in
19ff0 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61  serted into data
1a000 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20  base.** tables, 
1a010 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a020 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
1a030 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65  ion may be set e
1a040 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20  xplicitly by.** 
1a050 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73  [sqlite3_set_las
1a060 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1a070 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72  ].**.** Some vir
1a080 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
1a090 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49  mentations may I
1a0a0 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20  NSERT rows into 
1a0b0 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a  rowid tables as.
1a0c0 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69  ** part of commi
1a0d0 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  tting a transact
1a0e0 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75  ion (e.g. to flu
1a0f0 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61  sh data accumula
1a100 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  ted in memory.**
1a110 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68   to disk). In th
1a120 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75 65  is case subseque
1a130 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73  nt calls to this
1a140 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1a150 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73   the rowid.** as
1a160 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1a170 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53  ese internal INS
1a180 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20  ERT operations, 
1a190 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a  which leads to .
1a1a0 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72  ** unintuitive r
1a1b0 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20  esults. Virtual 
1a1c0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
1a1d0 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72  tions that do wr
1a1e0 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20  ite to rowid.** 
1a1f0 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77  tables in this w
1a200 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69  ay can avoid thi
1a210 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73  s problem by res
1a220 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69  toring the origi
1a230 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61  nal .** rowid va
1a240 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  lue using [sqlit
1a250 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1a260 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f  rt_rowid()] befo
1a270 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a  re returning .**
1a280 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20   control to the 
1a290 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  user..**.** ^(If
1a2a0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
1a2b0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
1a2c0 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 72  gger then this r
1a2d0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20  outine will .** 
1a2e0 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
1a2f0 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
1a300 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ed row as long a
1a310 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
1a320 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e   .** running. On
1a330 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 70  ce the trigger p
1a340 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65  rogram ends, the
1a350 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a360 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
1a370 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
1a380 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
1a390 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77 61  e the trigger wa
1a3a0 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  s fired.)^.**.**
1a3b0 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
1a3c0 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
1a3d0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
1a3e0 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
1a3f0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
1a400 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
1a410 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
1a420 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1a430 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
1a440 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
1a450 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
1a460 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
1a470 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
1a480 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
1a490 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
1a4a0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
1a4b0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1a4c0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
1a4d0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
1a4e0 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
1a4f0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1a500 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
1a510 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
1a520 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
1a530 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
1a540 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
1a550 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
1a560 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
1a570 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
1a580 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
1a590 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
1a5a0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
1a5b0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
1a5c0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
1a5d0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
1a5e0 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
1a5f0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
1a600 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
1a610 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
1a620 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
1a630 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
1a640 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
1a650 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
1a660 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
1a670 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
1a680 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
1a690 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1a6a0 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
1a6b0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
1a6c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1a6d0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1a6e0 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
1a6f0 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
1a700 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
1a710 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a720 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
1a730 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1a740 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
1a750 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
1a760 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
1a770 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
1a780 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
1a790 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
1a7a0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1a7b0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1a7c0 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
1a7d0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1a7e0 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
1a7f0 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
1a800 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
1a810 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
1a820 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
1a830 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
1a840 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
1a850 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a860 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74   CAPI3REF: Set t
1a870 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  he Last Insert R
1a880 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d  owid value..** M
1a890 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1a8a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1a8b0 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1a8c0 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74  _rowid(D, R) met
1a8d0 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61  hod allows the a
1a8e0 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
1a8f0 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72   set the value r
1a900 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69  eturned by calli
1a910 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  ng sqlite3_last_
1a920 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
1a930 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74  to R .** without
1a940 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77   inserting a row
1a950 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
1a960 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  se..*/.void sqli
1a970 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
1a980 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
1a990 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  3*,sqlite3_int64
1a9a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a9b0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
1a9c0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
1a9d0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
1a9e0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1a9f0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
1aa00 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1aa10 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
1aa20 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
1aa30 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
1aa40 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
1aa50 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
1aa60 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1aa70 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
1aa80 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1aa90 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
1aaa0 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
1aab0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
1aac0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
1aad0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
1aae0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
1aaf0 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
1ab00 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
1ab10 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
1ab20 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
1ab30 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
1ab40 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
1ab50 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1ab60 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
1ab70 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
1ab80 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
1ab90 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
1aba0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
1abb0 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
1abc0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
1abd0 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
1abe0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
1abf0 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
1ac00 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
1ac10 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1ac20 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1ac30 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
1ac40 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1ac50 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
1ac60 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
1ac70 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
1ac80 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
1ac90 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
1aca0 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
1acb0 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
1acc0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
1acd0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1ace0 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
1acf0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
1ad00 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
1ad10 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
1ad20 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
1ad30 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
1ad40 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
1ad50 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
1ad60 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
1ad70 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
1ad80 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
1ad90 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
1ada0 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
1adb0 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
1adc0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
1add0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1ade0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
1adf0 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
1ae00 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1ae10 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
1ae20 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
1ae30 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
1ae40 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
1ae50 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
1ae60 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
1ae70 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
1ae80 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1ae90 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
1aea0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1aeb0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
1aec0 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
1aed0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
1aee0 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
1aef0 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
1af00 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
1af10 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
1af20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
1af30 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1af40 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
1af50 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
1af60 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
1af70 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
1af80 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1af90 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1afa0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
1afb0 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
1afc0 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
1afd0 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
1afe0 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
1aff0 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
1b000 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
1b010 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
1b020 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
1b030 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1b040 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
1b050 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
1b060 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
1b070 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
1b080 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
1b090 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
1b0a0 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
1b0b0 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
1b0c0 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
1b0d0 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
1b0e0 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
1b0f0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1b100 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1b110 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1b120 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
1b130 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
1b140 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
1b150 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
1b160 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
1b170 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
1b180 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
1b190 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
1b1a0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1b1b0 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
1b1c0 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
1b1d0 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
1b1e0 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
1b1f0 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
1b200 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
1b210 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
1b220 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1b230 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
1b240 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
1b250 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
1b260 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
1b270 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
1b280 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1b290 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1b2a0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1b2b0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1b2c0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1b2d0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1b2e0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1b2f0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1b300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b310 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1b320 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1b330 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1b340 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1b350 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
1b360 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
1b370 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
1b380 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
1b390 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1b3a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
1b3b0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
1b3c0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
1b3d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1b3e0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1b3f0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1b400 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
1b410 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d  rows inserted, m
1b420 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65  odified or.** de
1b430 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e  leted by all [IN
1b440 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20  SERT], [UPDATE] 
1b450 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
1b460 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64  ements completed
1b470 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61  .** since the da
1b480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b490 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e  n was opened, in
1b4a0 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78  cluding those ex
1b4b0 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72  ecuted as.** par
1b4c0 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
1b4d0 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e  grams. ^Executin
1b4e0 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
1b4f0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1b500 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66  t.** does not af
1b510 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72  fect the value r
1b520 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1b530 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1b540 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e  ()..** .** ^Chan
1b550 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74  ges made as part
1b560 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   of [foreign key
1b570 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e   actions] are in
1b580 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a  cluded in the.**
1b590 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73   count, but thos
1b5a0 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  e made as part o
1b5b0 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
1b5c0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
1b5d0 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61  are.** not. ^Cha
1b5e0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1b5f0 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
1b600 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f  ted by INSTEAD O
1b610 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61  F triggers .** a
1b620 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1b630 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  ** .** See also 
1b640 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
1b650 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1b660 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
1b670 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
1b680 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
1b690 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
1b6a0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1b6b0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1b6c0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1b6d0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1b6e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b6f0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1b700 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1b710 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1b720 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
1b730 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
1b740 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1b750 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1b760 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1b770 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
1b780 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1b790 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
1b7a0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
1b7b0 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
1b7c0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1b7d0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1b7e0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1b7f0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1b800 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1b810 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1b820 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1b830 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1b840 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1b850 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1b860 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1b870 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1b880 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1b890 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1b8a0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1b8b0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1b8c0 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1b8d0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1b8e0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1b8f0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1b900 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1b910 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1b920 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1b930 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1b940 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1b950 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1b960 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1b970 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1b980 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1b990 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1b9a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b9b0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1b9c0 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1b9d0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1b9e0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1b9f0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1ba00 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1ba10 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1ba20 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1ba30 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1ba40 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ba50 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1ba60 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1ba70 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1ba80 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1ba90 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1baa0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1bab0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1bac0 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1bad0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1bae0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1baf0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1bb00 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1bb10 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1bb20 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1bb30 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1bb40 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1bb50 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1bb60 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1bb70 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1bb80 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1bb90 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1bba0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1bbb0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1bbc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1bbd0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1bbe0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1bbf0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1bc00 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1bc10 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1bc20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bc30 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1bc40 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1bc50 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1bc60 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1bc70 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1bc80 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1bc90 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1bca0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1bcb0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1bcc0 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1bcd0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1bce0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1bcf0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1bd00 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bd10 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1bd20 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1bd30 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1bd40 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1bd50 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1bd60 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1bd70 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1bd80 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1bd90 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1bda0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1bdb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bdc0 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1bdd0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1bde0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1bdf0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1be00 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1be10 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1be20 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1be30 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1be40 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1be50 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1be60 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69   returns..*/.voi
1be70 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
1be80 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
1be90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bea0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
1beb0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
1bec0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
1bed0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1bee0 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
1bef0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
1bf00 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
1bf10 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
1bf20 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
1bf30 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
1bf40 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1bf50 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
1bf60 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
1bf70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
1bf80 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
1bf90 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
1bfa0 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
1bfb0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
1bfc0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
1bfd0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
1bfe0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
1bff0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1c000 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
1c010 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
1c020 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
1c030 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
1c040 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
1c050 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
1c060 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
1c070 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
1c080 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
1c090 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
1c0a0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
1c0b0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
1c0c0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
1c0d0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
1c0e0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
1c0f0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
1c100 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
1c110 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
1c120 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
1c130 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
1c140 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
1c150 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
1c160 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
1c170 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
1c180 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
1c190 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
1c1a0 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
1c1b0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
1c1c0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
1c1d0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1c1e0 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
1c1f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
1c200 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
1c210 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
1c220 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
1c230 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
1c240 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1c250 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1c260 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
1c270 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1c280 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
1c290 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
1c2a0 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
1c2b0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
1c2c0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
1c2d0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
1c2e0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1c2f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
1c300 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
1c310 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
1c320 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
1c330 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1c340 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
1c350 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1c360 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
1c370 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
1c380 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
1c390 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
1c3a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1c3b0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
1c3c0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
1c3d0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
1c3e0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1c3f0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1c400 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
1c410 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
1c420 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1c430 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
1c440 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1c450 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1c460 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
1c470 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1c480 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1c490 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
1c4a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c4b0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
1c4c0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
1c4d0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
1c4e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1c4f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
1c500 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
1c510 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
1c520 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
1c530 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
1c540 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
1c550 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
1c560 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20  _BUSY Errors.** 
1c570 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d  KEYWORDS: {busy-
1c580 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1c590 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d  } {busy handler}
1c5a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1c5b0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
1c5c0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c5d0 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69  ler(D,X,P) routi
1c5e0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
1c5f0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  ck function X.**
1c600 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
1c610 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
1c620 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
1c630 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
1c640 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1c650 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1c660 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1c670 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1c680 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e  nnection] D when
1c690 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
1c6a0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
1c6b0 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b  s the table lock
1c6c0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1c6d0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c6e0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
1c6f0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1c700 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
1c710 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64  y_timeout()] and
1c720 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1c730 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  meout]..**.** ^I
1c740 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1c750 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
1c760 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1c770 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1c780 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
1c790 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
1c7a0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
1c7b0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
1c7c0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1c7d0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1c7e0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1c7f0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
1c800 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1c810 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1c820 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
1c830 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
1c840 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
1c850 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
1c860 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1c870 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
1c880 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
1c890 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1c8a0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
1c8b0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1c8c0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
1c8d0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
1c8e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
1c8f0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
1c900 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f  ed previously fo
1c910 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
1c920 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
1c930 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
1c940 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
1c950 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
1c960 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
1c970 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
1c980 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1c990 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
1c9a0 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74  is returned.** t
1c9b0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1c9c0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  n..** ^If the ca
1c9d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1c9e0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
1c9f0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
1ca00 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1ca10 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1ca20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
1ca30 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
1ca40 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
1ca50 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
1ca60 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
1ca70 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
1ca80 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
1ca90 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
1caa0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
1cab0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
1cac0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
1cad0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
1cae0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
1caf0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
1cb00 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
1cb10 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
1cb20 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65  _BUSY].** to the
1cb30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73   application ins
1cb40 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
1cb50 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61   the .** busy ha
1cb60 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
1cb70 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
1cb80 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
1cb90 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
1cba0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
1cbb0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
1cbc0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
1cbd0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
1cbe0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
1cbf0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1cc00 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
1cc10 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
1cc20 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
1cc30 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
1cc40 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
1cc50 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
1cc60 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
1cc70 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1cc80 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
1cc90 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1cca0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
1ccb0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
1ccc0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1ccd0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
1cce0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
1ccf0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
1cd00 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
1cd10 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
1cd20 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
1cd30 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
1cd40 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
1cd50 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
1cd60 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
1cd70 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
1cd80 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
1cd90 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
1cda0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
1cdb0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
1cdc0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
1cdd0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
1cde0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
1cdf0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
1ce00 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
1ce10 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1ce20 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1ce30 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
1ce40 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
1ce50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ce60 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
1ce70 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
1ce80 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
1ce90 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
1cea0 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
1ceb0 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
1cec0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1ced0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65  meout()].** or e
1cee0 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d  valuating [PRAGM
1cef0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e  A busy_timeout=N
1cf00 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68  ] will change th
1cf10 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
1cf20 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72  r and thus clear
1cf30 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1cf40 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  set busy handler
1cf50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
1cf60 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1cf70 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
1cf80 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
1cf90 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
1cfa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1cfb0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1cfc0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e  usy handler.  In
1cfd0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
1cfe0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1cff0 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  r is not reentra
1d000 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  nt.  Any such ac
1d010 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
1d020 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
1d030 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
1d040 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
1d050 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
1d060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d070 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
1d080 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1d090 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1d0a0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
1d0b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
1d0c0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
1d0d0 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  3*,int(*)(void*,
1d0e0 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  int),void*);../*
1d0f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1d100 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1d110 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1d120 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1d130 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
1d140 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1d150 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
1d160 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
1d170 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
1d180 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
1d190 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
1d1a0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
1d1b0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
1d1c0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
1d1d0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
1d1e0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1d1f0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1d200 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
1d210 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
1d220 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1d230 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1d240 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
1d250 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
1d260 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
1d270 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
1d280 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
1d290 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
1d2a0 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
1d2b0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
1d2c0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
1d2d0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
1d2e0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
1d2f0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
1d300 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
1d310 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1d320 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1d330 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
1d340 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1d350 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
1d360 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
1d370 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
1d380 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
1d390 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1d3a0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1d3b0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1d3c0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1d3d0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1d3e0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1d3f0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1d400 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1d410 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73  so:  [PRAGMA bus
1d420 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e  y_timeout].*/.in
1d430 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1d440 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1d450 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1d460 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1d470 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1d480 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1d490 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ies.** METHOD: s
1d4a0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69  qlite3.**.** Thi
1d4b0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1d4c0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1d4d0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1d4e0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1d4f0 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1d500 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1d510 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1d520 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1d530 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1d540 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1d550 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1d560 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1d570 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1d580 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1d590 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1d5a0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1d5b0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1d5c0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1d5d0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1d5e0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1d5f0 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1d600 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1d610 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1d620 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1d630 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1d640 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1d650 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1d660 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1d670 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1d680 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1d690 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1d6a0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1d6b0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1d6c0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1d6d0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1d6e0 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1d6f0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1d700 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d710 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1d720 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1d730 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1d740 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1d750 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1d760 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1d770 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1d780 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1d790 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1d7a0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1d7b0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1d7c0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1d7d0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1d7e0 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1d7f0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1d800 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1d810 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1d820 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1d830 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d840 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1d850 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1d860 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1d870 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1d880 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1d890 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1d8a0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1d8b0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1d8c0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1d8d0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1d8e0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1d8f0 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1d900 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1d910 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1d920 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1d930 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1d940 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1d950 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1d960 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1d970 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1d980 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1d990 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1d9a0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1d9b0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1d9c0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1d9d0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1d9e0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1d9f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1da00 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1da10 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1da20 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1da30 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1da40 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1da50 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1da60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1da70 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1da80 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1da90 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1daa0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1dab0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1dac0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1dad0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1dae0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1daf0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1db00 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1db10 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1db20 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1db30 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1db40 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1db50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1db60 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1db70 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1db80 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1db90 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1dba0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1dbb0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1dbc0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1dbd0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1dbe0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1dbf0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1dc00 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1dc10 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1dc20 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1dc30 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1dc40 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1dc50 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1dc60 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1dc70 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1dc80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1dc90 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1dca0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1dcb0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1dcc0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1dcd0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1dce0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1dcf0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1dd00 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1dd10 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1dd20 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1dd30 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1dd40 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1dd50 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1dd60 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1dd70 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1dd80 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1dd90 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1dda0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1ddb0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1ddc0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1ddd0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1dde0 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1ddf0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1de00 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1de10 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1de20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1de30 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1de40 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1de50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1de60 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1de70 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1de80 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1de90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1dea0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1deb0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1dec0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1ded0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1dee0 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1def0 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1df00 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1df10 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1df20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1df30 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1df40 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1df50 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1df60 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1df70 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1df80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1df90 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1dfa0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1dfb0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1dfc0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1dfd0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1dfe0 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1dff0 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1e000 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1e010 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1e020 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1e030 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1e040 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1e050 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1e060 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1e070 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1e080 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1e090 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1e0a0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1e0b0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1e0c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1e0d0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1e0e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
1e0f0 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
1e100 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
1e110 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
1e120 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
1e130 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
1e140 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
1e150 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
1e160 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
1e170 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
1e180 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
1e190 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
1e1a0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1e1b0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
1e1c0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
1e1d0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
1e1e0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1e1f0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
1e200 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1e210 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
1e220 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
1e230 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
1e240 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
1e250 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1e260 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
1e270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e280 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
1e290 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
1e2a0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1e2b0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
1e2c0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
1e2d0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
1e2e0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
1e2f0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
1e300 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
1e310 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1e320 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73  s understand mos
1e330 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20  t of the common 
1e340 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  K&R formatting o
1e350 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20  ptions,.** plus 
1e360 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1e370 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72  non-standard for
1e380 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62  mats, detailed b
1e390 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  elow..** Note th
1e3a0 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d  at some of the m
1e3b0 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d  ore obscure form
1e3c0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66  atting options f
1e3d0 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d  rom recent.** C-
1e3e0 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64  library standard
1e3f0 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72  s are omitted fr
1e400 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e  om this implemen
1e410 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  tation..**.** ^T
1e420 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1e430 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1e440 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1e450 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1e460 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1e470 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1e480 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1e490 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
1e4a0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1e4b0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
1e4c0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
1e4d0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
1e4e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e4f0 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
1e500 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
1e510 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
1e520 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e530 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
1e540 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
1e550 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
1e560 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
1e570 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
1e580 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
1e590 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1e5a0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
1e5b0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
1e5c0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1e5d0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
1e5e0 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
1e5f0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
1e600 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
1e610 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1e620 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
1e630 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
1e640 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1e650 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
1e660 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
1e670 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
1e680 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
1e690 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
1e6a0 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
1e6b0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
1e6c0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
1e6d0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
1e6e0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
1e6f0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1e700 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
1e710 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
1e720 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1e730 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
1e740 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
1e750 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1e760 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1e770 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
1e780 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
1e790 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
1e7a0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
1e7b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1e7c0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
1e7d0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
1e7e0 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
1e7f0 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
1e800 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
1e810 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1e820 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1e830 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
1e840 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
1e850 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
1e860 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
1e870 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
1e880 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
1e890 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
1e8a0 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
1e8b0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
1e8c0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
1e8d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
1e8e0 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
1e8f0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
1e900 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
1e910 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
1e920 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
1e930 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
1e940 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
1e950 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
1e960 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
1e970 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
1e980 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
1e990 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1e9a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
1e9b0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1e9c0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
1e9d0 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
1e9e0 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
1e9f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1ea00 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
1ea10 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1ea20 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
1ea30 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
1ea40 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
1ea50 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
1ea60 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
1ea70 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
1ea80 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
1ea90 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
1eaa0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
1eab0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
1eac0 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e  ", "%Q", "%w" an
1ead0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
1eae0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
1eaf0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1eb00 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
1eb10 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
1eb20 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1eb30 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
1eb40 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
1eb50 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
1eb60 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
1eb70 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
1eb80 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
1eb90 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
1eba0 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
1ebb0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
1ebc0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
1ebd0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
1ebe0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
1ebf0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
1ec00 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
1ec10 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
1ec20 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1ec30 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
1ec40 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
1ec50 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
1ec60 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1ec70 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1ec80 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
1ec90 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
1eca0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
1ecb0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1ecc0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
1ecd0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
1ece0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1ecf0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1ed00 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1ed10 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1ed20 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1ed30 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1ed40 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1ed50 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1ed60 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1ed70 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1ed80 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1ed90 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1eda0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1edb0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1edc0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1edd0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1ede0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1edf0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1ee00 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1ee10 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1ee20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1ee30 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1ee40 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1ee50 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1ee60 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1ee70 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1ee80 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1ee90 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1eea0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1eeb0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1eec0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1eed0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1eee0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1eef0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1ef00 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1ef10 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1ef20 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1ef30 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1ef40 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1ef50 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1ef60 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1ef70 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1ef80 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1ef90 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1efa0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1efb0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1efc0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1efd0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1efe0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1eff0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1f000 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1f010 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1f020 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1f030 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1f040 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1f050 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1f060 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1f070 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1f080 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1f090 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1f0a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1f0b0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1f0c0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1f0d0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1f0e0 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1f0f0 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1f100 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1f110 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1f120 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1f130 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1f140 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1f150 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1f160 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1f170 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1f180 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1f190 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1f1a0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1f1b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1f1c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1f1d0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1f1e0 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1f1f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1f200 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1f210 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1f220 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1f230 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1f240 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1f250 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1f260 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20   option is like 
1f270 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74  "%q" except that
1f280 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a   it expects to.*
1f290 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77  * be contained w
1f2a0 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f  ithin double-quo
1f2b0 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73  tes instead of s
1f2c0 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e  ingle quotes, an
1f2d0 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20  d it.** escapes 
1f2e0 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65  the double-quote
1f2f0 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65   character inste
1f300 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65  ad of the single
1f310 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63  -quote.** charac
1f320 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22  ter.)^  The "%w"
1f330 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1f340 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  on is intended f
1f350 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74  or safely insert
1f360 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64  ing.** table and
1f370 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e   column names in
1f380 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64  to a constructed
1f390 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1f3a0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1f3b0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1f3c0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1f3d0 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1f3e0 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1f3f0 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1f400 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1f410 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1f420 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1f430 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1f440 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1f450 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1f460 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
1f470 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1f480 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
1f490 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
1f4a0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
1f4b0 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
1f4c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1f4d0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1f4e0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
1f4f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
1f500 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1f510 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1f520 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1f530 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1f540 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1f550 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1f560 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1f570 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1f580 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1f590 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1f5a0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1f5b0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1f5c0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1f5d0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1f5e0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1f5f0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1f600 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1f610 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1f620 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1f630 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1f640 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1f650 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1f660 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1f670 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1f680 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1f690 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1f6a0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1f6b0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1f6c0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1f6d0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1f6e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1f6f0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1f700 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1f710 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1f720 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1f730 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1f740 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1f750 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1f760 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1f770 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1f780 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1f790 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1f7a0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1f7b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1f7c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f7d0 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
1f7e0 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
1f7f0 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
1f800 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
1f810 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
1f820 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
1f830 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1f840 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
1f850 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
1f860 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1f870 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1f880 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1f890 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1f8a0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1f8b0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1f8c0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1f8d0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1f8e0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1f8f0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1f900 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1f910 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1f920 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1f930 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1f940 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1f950 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1f960 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1f970 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1f980 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1f990 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1f9a0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1f9b0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1f9c0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1f9d0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1f9e0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1f9f0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1fa00 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1fa10 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1fa20 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1fa30 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1fa40 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1fa50 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1fa60 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1fa70 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1fa80 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1fa90 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1faa0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1fab0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1fac0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1fad0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fae0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1faf0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
1fb00 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1fb10 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
1fb20 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1fb30 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1fb40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1fb50 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
1fb60 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
1fb70 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
1fb80 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1fb90 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
1fba0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1fbb0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1fbc0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1fbd0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1fbe0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
1fbf0 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
1fc00 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1fc10 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
1fc20 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1fc30 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1fc40 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1fc50 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1fc60 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1fc70 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
1fc80 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1fc90 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
1fca0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1fcb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1fcc0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1fcd0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1fce0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
1fcf0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
1fd00 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1fd10 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1fd20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1fd30 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1fd40 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1fd50 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1fd60 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1fd70 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1fd80 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1fd90 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1fda0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1fdb0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1fdc0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1fdd0 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1fde0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1fdf0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
1fe00 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
1fe10 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
1fe20 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1fe30 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1fe40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1fe50 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
1fe60 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
1fe70 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
1fe80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1fe90 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1fea0 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
1feb0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
1fec0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
1fed0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1fee0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
1fef0 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
1ff00 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
1ff10 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1ff20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ff30 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1ff40 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
1ff50 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
1ff60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1ff70 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
1ff80 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1ff90 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
1ffa0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
1ffb0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
1ffc0 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
1ffd0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1ffe0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
1fff0 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
20000 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
20010 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
20020 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
20030 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
20040 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
20050 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
20060 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
20070 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
20080 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
20090 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
200a0 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
200b0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
200c0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
200d0 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
200e0 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
200f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
20100 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
20110 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
20120 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
20130 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
20140 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
20150 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
20160 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
20170 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
20180 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
20190 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
201a0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
201b0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
201c0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
201d0 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
201e0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
201f0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
20200 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
20210 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
20220 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
20230 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
20240 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
20250 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
20260 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
20270 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
20280 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
20290 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
202a0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
202b0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
202c0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
202d0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
202e0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
202f0 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
20300 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
20310 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
20320 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
20330 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
20340 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
20350 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
20360 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
20370 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
20380 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
20390 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
203a0 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
203b0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
203c0 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
203d0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
203e0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
203f0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
20400 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
20410 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
20420 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
20430 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
20440 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
20450 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
20460 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
20470 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
20480 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
20490 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
204a0 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
204b0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
204c0 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
204d0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
204e0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
204f0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
20500 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
20510 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
20520 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
20530 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
20540 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
20550 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
20560 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
20570 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
20580 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
20590 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
205a0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
205b0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
205c0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
205d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
205e0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
205f0 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
20600 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
20610 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
20620 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
20630 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
20640 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
20650 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
20660 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
20670 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
20680 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
20690 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
206a0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
206b0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
206c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
206d0 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
206e0 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  t64);.void *sqli
206f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
20700 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  *, int);.void *s
20710 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
20720 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f  (void*, sqlite3_
20730 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  uint64);.void sq
20740 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
20750 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  );.sqlite3_uint6
20760 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
20770 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
20780 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
20790 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
207a0 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
207b0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
207c0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
207d0 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
207e0 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
207f0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
20800 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
20810 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
20820 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
20830 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
20840 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
20850 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
20860 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
20870 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
20880 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20890 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
208a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
208b0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
208c0 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
208d0 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
208e0 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
208f0 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
20900 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
20910 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
20920 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
20930 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
20940 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
20950 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
20960 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
20970 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
20980 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
20990 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
209a0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
209b0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
209c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
209d0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
209e0 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
209f0 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
20a00 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
20a10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
20a20 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
20a30 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
20a40 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
20a50 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
20a60 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
20a70 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
20a80 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
20a90 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
20aa0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
20ab0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
20ac0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
20ad0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
20ae0 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
20af0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20b00 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
20b10 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
20b20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
20b30 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
20b40 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
20b50 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
20b60 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
20b70 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
20b80 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
20b90 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
20ba0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
20bb0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
20bc0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
20bd0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
20be0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
20bf0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20c00 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
20c10 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
20c20 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
20c30 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
20c40 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
20c50 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
20c60 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
20c70 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
20c80 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
20c90 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
20ca0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
20cb0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
20cc0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
20cd0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
20ce0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
20cf0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
20d00 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
20d10 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
20d20 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
20d30 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
20d40 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
20d50 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
20d60 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
20d70 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
20d80 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
20d90 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
20da0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
20db0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
20dc0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
20dd0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
20de0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
20df0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
20e00 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
20e10 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
20e20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
20e30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
20e40 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
20e50 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
20e60 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
20e70 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
20e80 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
20e90 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
20ea0 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
20eb0 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
20ec0 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
20ed0 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
20ee0 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
20ef0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
20f00 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
20f10 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
20f20 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
20f30 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
20f40 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
20f50 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
20f60 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
20f70 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
20f80 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
20f90 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
20fa0 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
20fb0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
20fc0 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
20fd0 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
20fe0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
20ff0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
21000 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
21010 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
21020 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
21030 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
21040 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
21050 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
21060 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44  lite3.** KEYWORD
21070 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63  S: {authorizer c
21080 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e  allback}.**.** ^
21090 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
210a0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
210b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
210c0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
210d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
210e0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
210f0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
21100 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
21110 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21120 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
21130 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
21140 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
21150 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
21160 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
21170 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
21180 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21190 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
211a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
211b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
211c0 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  are16()], [sqlit
211d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
211e0 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  )],.** and [sqli
211f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
21200 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
21210 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
21220 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
21230 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
21240 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
21250 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
21260 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
21270 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
21280 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21290 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
212a0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
212b0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
212c0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
212d0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
212e0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
212f0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
21300 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
21310 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
21320 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
21330 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
21340 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
21350 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
21360 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
21370 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
21380 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
21390 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
213a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
213b0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
213c0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
213d0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
213e0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
213f0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
21400 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
21410 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
21420 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
21430 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
21440 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
21450 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
21460 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
21470 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
21480 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
21490 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
214a0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
214b0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
214c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
214d0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
214e0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
214f0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
21500 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
21510 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
21520 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
21530 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
21540 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21550 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
21560 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
21570 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
21580 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
21590 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
215a0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
215b0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
215c0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
215d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
215e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
215f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21600 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
21610 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
21620 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
21630 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21640 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
21650 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
21660 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
21670 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
21680 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
21690 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
216a0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
216b0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
216c0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
216d0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
216e0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
216f0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
21700 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
21710 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68  allback are eith
21720 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  er NULL pointers
21730 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   or zero-termina
21740 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74  ted strings.** t
21750 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
21760 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
21770 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
21780 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
21790 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
217a0 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65  s must always be
217b0 20 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63   prepared to enc
217c0 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f  ounter a NULL po
217d0 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20  inter in any.** 
217e0 6f 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72  of the third thr
217f0 6f 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70  ough the sixth p
21800 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
21810 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
21820 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
21830 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
21840 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
21850 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
21860 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
21870 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
21880 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
21890 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
218a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
218b0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
218c0 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
218d0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
218e0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
218f0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
21900 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
21910 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
21920 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
21930 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
21940 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
21950 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
21960 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
21970 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
21980 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
21990 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
219a0 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ble..** ^When a 
219b0 74 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e  table is referen
219c0 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54  ced by a [SELECT
219d0 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20  ] but no column 
219e0 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78  values are.** ex
219f0 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61  tracted from tha
21a00 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61  t table (for exa
21a10 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20  mple in a query 
21a20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20  like.** "SELECT 
21a30 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61  count(*) FROM ta
21a40 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51  b") then the [SQ
21a50 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f  LITE_READ] autho
21a60 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
21a70 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  * is invoked onc
21a80 65 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65  e for that table
21a90 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e   with a column n
21aa0 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65  ame that is an e
21ab0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  mpty string..** 
21ac0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
21ad0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
21ae0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
21af0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
21b00 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
21b10 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
21b20 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
21b30 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
21b40 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
21b50 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
21b60 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
21b70 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
21b80 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
21b90 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
21ba0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
21bb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
21bc0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
21bd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
21be0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
21bf0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
21c00 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
21c10 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
21c20 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
21c30 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
21c40 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
21c50 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
21c60 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
21c70 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
21c80 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
21c90 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
21ca0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
21cb0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
21cc0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
21cd0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
21ce0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
21cf0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
21d00 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
21d10 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
21d20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
21d30 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
21d40 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
21d50 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
21d60 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
21d70 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
21d80 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
21d90 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
21da0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
21db0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
21dc0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
21dd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
21de0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
21df0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
21e00 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
21e10 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
21e20 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
21e30 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
21e40 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
21e50 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
21e60 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
21e70 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
21e80 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
21e90 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
21ea0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
21eb0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
21ec0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
21ed0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
21ee0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
21ef0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
21f00 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
21f10 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
21f20 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
21f30 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
21f40 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
21f50 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
21f60 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
21f70 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
21f80 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
21f90 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
21fa0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
21fb0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
21fc0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
21fd0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
21fe0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
21ff0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
22000 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
22010 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
22020 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
22030 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
22040 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
22050 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
22060 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
22070 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
22080 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
22090 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
220a0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
220b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
220c0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
220d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
220e0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
220f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
22100 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
22110 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
22120 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
22130 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
22140 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
22150 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
22160 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
22170 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
22180 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
22190 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
221a0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
221b0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
221c0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
221d0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
221e0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
221f0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
22200 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
22210 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22220 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
22230 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
22240 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
22250 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
22260 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22270 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
22280 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
22290 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
222a0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
222b0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
222c0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
222d0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
222e0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
222f0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
22300 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
22310 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
22320 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
22330 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
22340 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
22350 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
22360 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
22370 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
22380 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
22390 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
223a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
223b0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
223c0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
223d0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
223e0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
223f0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
22400 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
22410 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
22420 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
22430 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
22440 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
22450 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
22460 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
22470 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22480 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
22490 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
224a0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
224b0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
224c0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
224d0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
224e0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
224f0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
22500 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
22510 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
22520 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
22530 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
22540 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
22550 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
22560 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
22570 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
22580 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
22590 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
225a0 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
225b0 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
225c0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
225d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
225e0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
225f0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
22600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
22610 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
22620 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
22630 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
22640 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22650 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
22660 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
22670 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
22680 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
22690 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
226a0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
226b0 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
226c0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
226d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
226e0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
226f0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
22700 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
22710 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
22720 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
22730 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
22740 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
22750 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
22760 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
22770 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
22780 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
22790 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
227a0 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
227b0 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
227c0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
227d0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
227e0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
227f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
22800 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
22810 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
22820 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
22830 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
22840 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
22850 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
22860 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
22870 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
22880 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
22890 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
228a0 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
228b0 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
228c0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
228d0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
228e0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
228f0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
22900 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
22910 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
22920 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
22930 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
22940 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
22950 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
22960 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
22970 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
22980 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
22990 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
229a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
229b0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
229c0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
229d0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
229e0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
229f0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
22a00 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
22a10 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
22a20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
22a30 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
22a40 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
22a50 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
22a60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22a70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22a80 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
22a90 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
22aa0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
22ab0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
22ac0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
22ad0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22ae0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
22af0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22b00 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
22b10 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
22b20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22b30 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22b40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22b50 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
22b60 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
22b70 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
22b80 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22b90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22ba0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
22bb0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
22bc0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22bd0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22be0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22bf0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
22c00 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
22c10 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22c20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22c30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22c40 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
22c50 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
22c60 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
22c70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22c80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22c90 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
22ca0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
22cb0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
22cc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22cd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22ce0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
22cf0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
22d00 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
22d10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22d20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d30 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
22d40 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
22d50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22d60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22d70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22d80 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
22d90 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
22da0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
22db0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22dd0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
22de0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
22df0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22e00 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22e10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22e20 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
22e30 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
22e40 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
22e50 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22e70 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
22e80 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
22e90 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22ea0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22eb0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22ec0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
22ed0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
22ee0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22ef0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22f00 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22f10 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
22f20 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
22f30 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22f40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22f50 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
22f60 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
22f70 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
22f80 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
22f90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22fa0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
22fb0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
22fc0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
22fd0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22fe0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22ff0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
23000 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
23010 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
23020 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
23030 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23040 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
23050 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
23060 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
23070 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
23080 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
23090 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
230a0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
230b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
230c0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
230d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
230e0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
230f0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
23100 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23110 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23120 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23130 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
23140 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
23150 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
23160 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23170 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23180 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
23190 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
231a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
231b0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
231c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
231d0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
231e0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
231f0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
23200 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
23210 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23220 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
23230 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
23240 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
23250 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
23270 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
23280 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
23290 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
232a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
232b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
232c0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
232d0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
232e0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
232f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23300 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
23310 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
23320 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
23330 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23340 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23350 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
23360 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
23370 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
23380 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
23390 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
233a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
233b0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
233c0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
233d0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
233e0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
233f0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
23400 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
23410 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
23420 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
23430 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
23440 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
23450 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
23460 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
23470 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
23480 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
23490 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
234a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
234b0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
234c0 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
234d0 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
234e0 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
234f0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
23500 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23510 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
23520 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
23530 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
23540 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
23550 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23560 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
23570 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55  re deprecated. U
23580 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
23590 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65  trace_v2()] inte
235a0 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64  rface.** instead
235b0 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73   of the routines
235c0 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e   described here.
235d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
235e0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
235f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
23600 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
23610 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
23620 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
23630 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
23640 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
23650 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
23660 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
23670 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
23680 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
23690 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
236a0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
236b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
236c0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
236d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
236e0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
236f0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
23700 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23710 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
23720 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
23730 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
23740 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
23750 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
23760 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
23770 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
23780 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
23790 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
237a0 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
237b0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
237c0 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
237d0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
237e0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
237f0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
23800 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
23810 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
23820 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
23830 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
23840 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
23850 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
23860 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
23870 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
23880 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
23890 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
238a0 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
238b0 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
238c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
238d0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
238e0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
238f0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
23900 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
23910 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
23920 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
23930 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
23940 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
23950 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
23960 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
23970 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
23980 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
23990 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
239a0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
239b0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
239c0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
239d0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
239e0 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
239f0 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
23a00 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
23a10 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
23a20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
23a30 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
23a40 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
23a50 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
23a60 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
23a70 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
23a80 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
23a90 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
23aa0 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
23ab0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
23ac0 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
23ad0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
23ae0 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
23af0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
23b00 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
23b10 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
23b20 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
23b30 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
23b40 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
23b50 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
23b60 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
23b70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
23b80 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  race(sqlite3*,. 
23b90 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28    void(*xTrace)(
23ba0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
23bb0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
23bc0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
23bd0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
23be0 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
23bf0 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
23c00 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
23c10 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
23c20 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
23c30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
23c40 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64   Trace Event Cod
23c50 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
23c60 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a  SQLITE_TRACE.**.
23c70 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
23c80 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73  ts identify clas
23c90 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68  ses of events th
23ca0 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f  at can be monito
23cb0 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  red.** using the
23cc0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
23cd0 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f  v2()] tracing lo
23ce0 67 69 63 2e 20 20 54 68 65 20 74 68 69 72 64 20  gic.  The third 
23cf0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
23d00 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23d10 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20  ()] is an OR-ed 
23d20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f  combination of o
23d30 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a  ne or more of.**
23d40 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
23d50 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20  onstants.  ^The 
23d60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
23d70 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
23d80 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f  back.** is one o
23d90 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
23da0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
23db0 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e   New tracing con
23dc0 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64  stants may be ad
23dd0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
23de0 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  leases..**.** ^A
23df0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
23e00 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  has four argumen
23e10 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c  ts: xCallback(T,
23e20 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20  C,P,X)..** ^The 
23e30 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  T argument is on
23e40 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  e of the integer
23e50 20 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76   type codes abov
23e60 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  e..** ^The C arg
23e70 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
23e80 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
23e90 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
23ea0 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
23eb0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
23ec0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23ed0 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64  )]..** The P and
23ee0 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65   X arguments are
23ef0 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20   pointers whose 
23f00 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20  meanings depend 
23f10 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  on T..**.** <dl>
23f20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
23f30 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51  CE_STMT]] <dt>SQ
23f40 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c  LITE_TRACE_STMT<
23f50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
23f60 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
23f70 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  T callback is in
23f80 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65  voked when a pre
23f90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
23fa0 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  ** first begins 
23fb0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73  running and poss
23fc0 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69  ibly at other ti
23fd0 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a  mes during the.*
23fe0 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  * execution of t
23ff0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
24000 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61  ement, such as a
24010 74 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65  t the start of e
24020 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73  ach.** trigger s
24030 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20  ubprogram. ^The 
24040 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
24050 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
24060 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
24070 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61  ement]. ^The X a
24080 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
24090 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
240a0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
240b0 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20   unexpanded SQL 
240c0 74 65 78 74 20 6f 66 20 74 68 65 20 70 72 65 70  text of the prep
240d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
240e0 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  r an SQL comment
240f0 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
24100 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69  tes the invocati
24110 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e  on of a trigger.
24120 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20    ^The callback 
24130 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74  can compute.** t
24140 68 65 20 73 61 6d 65 20 74 65 78 74 20 74 68 61  he same text tha
24150 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65  t would have bee
24160 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
24170 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
24180 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e  3_trace()].** in
24190 74 65 72 66 61 63 65 20 62 79 20 75 73 69 6e 67  terface by using
241a0 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
241b0 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69  when X begins wi
241c0 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f  th "--" and invo
241d0 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  king.** [sqlite3
241e0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
241f0 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  ] otherwise..**.
24200 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
24210 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e  E_PROFILE]] <dt>
24220 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
24230 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FILE</dt>.** <dd
24240 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
24250 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61  E_PROFILE callba
24260 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70 72  ck provides appr
24270 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61  oximately the sa
24280 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  me.** informatio
24290 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64 65 64  n as is provided
242a0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
242b0 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c  _profile()] call
242c0 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  back..** ^The P 
242d0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
242e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72  inter to the [pr
242f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24300 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61  ] and the.** X a
24310 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
24320 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67  o a 64-bit integ
24330 65 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20  er which is the 
24340 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20  estimated of.** 
24350 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61  the number of na
24360 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68  nosecond that th
24370 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
24380 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
24390 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
243a0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
243b0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
243c0 65 64 20 77 68 65 6e 20 74 68 65 20 73 74 61 74  ed when the stat
243d0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a  ement finishes..
243e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
243f0 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53  RACE_ROW]] <dt>S
24400 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c  QLITE_TRACE_ROW<
24410 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
24420 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
24430 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24440 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
24450 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
24460 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20  ement generates 
24470 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
24480 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68  result.  .** ^Th
24490 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
244a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
244b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
244c0 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
244d0 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75   X argument is u
244e0 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  nused..**.** [[S
244f0 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
24500 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
24510 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a  RACE_CLOSE</dt>.
24520 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
24530 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61  E_TRACE_CLOSE ca
24540 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
24550 64 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  d when a databas
24560 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
24570 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20  closes..** ^The 
24580 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
24590 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
245a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
245b0 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  ion] object.** a
245c0 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  nd the X argumen
245d0 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20  t is unused..** 
245e0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
245f0 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54   SQLITE_TRACE_ST
24600 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a 23 64  MT       0x01.#d
24610 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
24620 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78  CE_PROFILE    0x
24630 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
24640 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20  E_TRACE_ROW     
24650 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20     0x04.#define 
24660 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
24670 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a  SE      0x08../*
24680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
24690 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20  L Trace Hook.** 
246a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
246b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
246c0 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c  e3_trace_v2(D,M,
246d0 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  X,P) interface r
246e0 65 67 69 73 74 65 72 73 20 61 20 74 72 61 63 65  egisters a trace
246f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
24700 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20  ction X against 
24710 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24720 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70  tion] D, using p
24730 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a  roperty mask M.*
24740 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f  * and context po
24750 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68  inter P.  ^If th
24760 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a  e X callback is.
24770 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68  ** NULL or if th
24780 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f  e M mask is zero
24790 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69  , then tracing i
247a0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65  s disabled.  The
247b0 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73  .** M argument s
247c0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69 74  hould be the bit
247d0 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69  wise OR-ed combi
247e0 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72  nation of.** zer
247f0 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54  o or more [SQLIT
24800 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e  E_TRACE] constan
24810 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  ts..**.** ^Each 
24820 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73  call to either s
24830 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
24840 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
24850 76 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a  v2() overrides .
24860 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79  ** (cancels) any
24870 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20   prior calls to 
24880 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
24890 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
248a0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  _v2()..**.** ^Th
248b0 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e X callback is 
248c0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
248d0 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e   any of the even
248e0 74 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ts identified by
248f0 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75   .** mask M occu
24900 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72  r.  ^The integer
24910 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
24920 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  om the callback 
24930 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  is currently.** 
24940 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20  ignored, though 
24950 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20  this may change 
24960 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
24970 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a  es.  Callback.**
24980 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
24990 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a   should return z
249a0 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75  ero to ensure fu
249b0 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69  ture compatibili
249c0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61  ty..**.** ^A tra
249d0 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ce callback is i
249e0 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72  nvoked with four
249f0 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c   arguments: call
24a00 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
24a10 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
24a20 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
24a30 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a  [SQLITE_TRACE].*
24a40 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69  * constants to i
24a50 6e 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20  ndicate why the 
24a60 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76  callback was inv
24a70 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  oked..** ^The C 
24a80 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
24a90 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
24aa0 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68  t pointer..** Th
24ab0 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
24ac0 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
24ad0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
24ae0 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
24af0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74  ** The sqlite3_t
24b00 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66  race_v2() interf
24b10 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
24b20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c  to replace the l
24b30 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
24b40 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  ces [sqlite3_tra
24b50 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ce()] and [sqlit
24b60 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62  e3_profile()], b
24b70 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20  oth of which.** 
24b80 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a  are deprecated..
24b90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
24ba0 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  race_v2(.  sqlit
24bb0 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20  e3*,.  unsigned 
24bc0 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43  uMask,.  int(*xC
24bd0 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65  allback)(unsigne
24be0 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f  d,void*,void*,vo
24bf0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43  id*),.  void *pC
24c00 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tx.);../*.** CAP
24c10 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
24c20 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
24c30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
24c40 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
24c50 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
24c60 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
24c70 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
24c80 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
24c90 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
24ca0 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
24cb0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
24cc0 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
24cd0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
24ce0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
24cf0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
24d00 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
24d10 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
24d20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
24d30 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
24d40 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
24d50 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
24d60 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
24d70 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
24d80 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
24d90 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
24da0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
24db0 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
24dc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
24dd0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
24de0 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
24df0 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61  meter N is the a
24e00 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65  pproximate numbe
24e10 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
24e20 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
24e30 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
24e40 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
24e50 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
24e60 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
24e70 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20  the callback X. 
24e80 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74   ^If N is less t
24e90 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65  han one then the
24ea0 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e   progress.** han
24eb0 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  dler is disabled
24ec0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
24ed0 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
24ee0 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
24ef0 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
24f00 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
24f10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
24f20 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
24f30 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
24f40 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
24f50 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
24f60 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
24f70 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables 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 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
24fa0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
24fb0 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
24fc0 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
24fd0 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
24fe0 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
24ff0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
25000 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
25010 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
25020 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
25030 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
25040 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
25050 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
25060 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
25070 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
25080 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
25090 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
250a0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
250b0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
250c0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
250d0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
250e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
250f0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
25100 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
25110 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
25120 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
25130 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
25140 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
25150 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
25160 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
25170 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
25180 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
25190 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
251a0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
251b0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
251c0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
251d0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
251e0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
251f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
25200 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
25210 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
25220 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f  Connection.** CO
25230 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
25240 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
25250 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
25260 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
25270 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
25280 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
25290 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
252a0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
252b0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
252c0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
252d0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
252e0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
252f0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
25300 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
25310 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
25320 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
25330 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
25340 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25350 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
25360 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
25370 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
25380 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
25390 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
253a0 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
253b0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
253c0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
253d0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
253e0 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
253f0 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
25400 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
25410 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
25420 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
25430 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
25440 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
25450 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
25460 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
25470 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
25480 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
25490 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
254a0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
254b0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
254c0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
254d0 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
254e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
254f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
25500 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
25510 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
25520 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
25530 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
25540 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
25550 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
25560 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
25570 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
25580 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
25590 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
255a0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
255b0 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46  ding will be UTF
255c0 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  -8 for databases
255d0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
255e0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
255f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
25600 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66  _v2().  ^The def
25610 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
25620 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63  r databases.** c
25630 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c  reated using sql
25640 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69  ite3_open16() wi
25650 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20  ll be UTF-16 in 
25660 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
25670 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  order..**.** Whe
25680 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
25690 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
256a0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
256b0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
256c0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
256d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
256e0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
256f0 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
25700 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
25710 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
25720 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
25730 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
25740 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
25750 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25760 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
25770 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
25780 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
25790 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
257a0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
257b0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
257c0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
257d0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
257e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
257f0 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
25800 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
25810 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
25820 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
25830 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
25840 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
25850 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
25860 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
25870 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25880 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
25890 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
258a0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
258b0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
258c0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
258d0 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
258e0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
258f0 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
25900 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
25910 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
25920 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
25930 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
25940 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
25950 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
25960 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
25970 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
25980 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
25990 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
259a0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
259b0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
259c0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
259d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
259e0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
259f0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
25a00 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
25a10 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
25a20 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
25a30 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
25a40 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
25a50 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
25a60 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
25a70 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
25a80 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
25a90 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
25aa0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
25ab0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
25ac0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
25ad0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
25ae0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
25af0 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
25b00 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
25b10 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
25b20 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
25b30 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
25b40 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
25b50 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
25b60 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
25b70 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
25b80 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
25b90 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
25ba0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
25bb0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
25bc0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
25bd0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
25be0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
25bf0 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
25c00 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
25c10 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
25c20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
25c30 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
25c40 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
25c50 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
25c60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
25c70 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
25c80 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
25c90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
25ca0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
25cb0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
25cc0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
25cd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25ce0 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
25cf0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
25d00 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
25d10 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
25d20 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
25d30 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
25d40 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
25d50 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
25d60 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
25d70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25d80 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
25d90 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
25da0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25db0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
25dc0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
25dd0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
25de0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
25df0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
25e00 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
25e10 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
25e20 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
25e30 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
25e40 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
25e50 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
25e60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
25e70 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
25e80 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
25e90 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
25ea0 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
25eb0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
25ec0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
25ed0 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
25ee0 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
25ef0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
25f00 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
25f10 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
25f20 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
25f30 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
25f40 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
25f50 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
25f60 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
25f70 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
25f80 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
25f90 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
25fa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
25fb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25fc0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
25fd0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
25fe0 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
25ff0 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
26000 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
26010 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
26020 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
26030 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
26040 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
26050 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
26060 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
26070 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
26080 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
26090 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
260a0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
260b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
260c0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
260d0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
260e0 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
260f0 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
26100 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
26110 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
26120 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
26130 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
26140 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
26150 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
26160 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
26170 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
26180 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
26190 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
261a0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
261b0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
261c0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
261d0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
261e0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
261f0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
26200 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
26210 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
26220 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
26230 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
26240 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
26250 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
26260 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
26270 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
26280 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
26290 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
262a0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
262b0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
262c0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
262d0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
262e0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
262f0 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
26300 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
26310 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
26320 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
26330 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
26340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26350 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
26360 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
26370 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
26380 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
26390 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
263a0 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
263b0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
263c0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
263d0 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
263e0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
263f0 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
26400 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
26410 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
26420 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
26430 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
26440 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
26450 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
26460 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
26470 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
26480 65 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  et in the third 
26490 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
264a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
264b0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
264c0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
264d0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
264e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
264f0 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
26500 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
26510 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
26520 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
26530 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
26540 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
26550 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
26560 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
26570 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
26580 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
26590 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
265a0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
265b0 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
265c0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
265d0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
265e0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
265f0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
26600 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
26610 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
26620 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
26630 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
26640 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
26650 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
26660 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
26670 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
26680 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
26690 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
266a0 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
266b0 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
266c0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
266d0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
266e0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
266f0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
26700 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
26710 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
26720 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
26730 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
26740 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
26750 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
26760 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
26770 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
26780 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
26790 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
267a0 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
267b0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
267c0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
267d0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
267e0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
267f0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
26800 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
26810 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
26820 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
26830 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
26840 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
26850 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
26860 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
26870 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
26880 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
26890 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
268a0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
268b0 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
268c0 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74   ^(On windows, t
268d0 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
268e0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
268f0 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
26900 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
26910 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
26920 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )^.**.** [[core 
26930 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
26940 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
26950 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
26960 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
26970 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
26980 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
26990 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
269a0 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
269b0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
269c0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
269d0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
269e0 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c  ite and its buil
269f0 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74  t-in [VFSes] int
26a00 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f  erpret the.** fo
26a10 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61  llowing query pa
26a20 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
26a30 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
26a40 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
26a50 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
26a60 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
26a70 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
26a80 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
26a90 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
26aa0 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
26ab0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
26ac0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
26ad0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
26ae0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
26af0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
26b00 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
26b10 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
26b20 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
26b30 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
26b40 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
26b50 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
26b60 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
26b70 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
26b80 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
26b90 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
26ba0 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
26bb0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
26bc0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
26bd0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
26be0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
26bf0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
26c00 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
26c10 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
26c20 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
26c30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
26c40 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
26c50 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
26c60 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
26c70 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
26c80 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
26c90 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
26ca0 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
26cb0 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
26cc0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
26cd0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
26ce0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
26cf0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
26d00 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
26d10 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
26d20 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
26d30 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
26d40 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
26d50 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
26d60 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
26d70 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
26d80 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
26d90 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
26da0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
26db0 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
26dc0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
26dd0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
26de0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
26df0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
26e00 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
26e10 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
26e20 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
26e30 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
26e40 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
26e50 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
26e60 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
26e70 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
26e80 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
26e90 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
26ea0 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
26eb0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
26ec0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
26ed0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
26ee0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
26ef0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
26f00 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
26f10 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
26f20 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
26f30 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
26f40 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
26f50 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
26f60 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
26f70 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
26f80 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
26f90 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
26fa0 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
26fb0 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
26fc0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
26fd0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
26fe0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
26ff0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
27000 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
27010 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
27020 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
27030 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
27040 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
27050 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
27060 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
27070 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
27080 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
27090 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
270a0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
270b0 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
270c0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
270d0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
270e0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
270f0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
27100 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
27110 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
27120 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
27130 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
27140 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
27150 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
27160 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
27170 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
27180 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
27190 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
271a0 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
271b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
271c0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
271d0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
271e0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
271f0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
27200 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
27210 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
27220 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
27230 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
27240 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
27250 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c   flag..**.**  <l
27260 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20  i> <b>psow</b>: 
27270 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65  ^The psow parame
27280 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68  ter indicates wh
27290 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
272a0 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61  .**     [powersa
272b0 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72  fe overwrite] pr
272c0 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64  operty does or d
272d0 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f  oes not apply to
272e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72   the.**     stor
272f0 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69  age media on whi
27300 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
27310 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a  file resides..**
27320 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c  .**  <li> <b>nol
27330 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f  ock</b>: ^The no
27340 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  lock parameter i
27350 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
27360 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  y parameter.**  
27370 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20     which if set 
27380 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f  disables file lo
27390 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63  cking in rollbac
273a0 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e  k journal modes.
273b0 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73    This.**     is
273c0 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65   useful for acce
273d0 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  ssing a database
273e0 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d   on a filesystem
273f0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a   that does not.*
27400 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f  *     support lo
27410 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a  cking.  Caution:
27420 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75    Database corru
27430 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75  ption might resu
27440 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20  lt if two.**    
27450 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73   or more process
27460 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20  es write to the 
27470 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e  same database an
27480 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f  d any one of tho
27490 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73  se.**     proces
274a0 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d  ses uses nolock=
274b0 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  1..**.**  <li> <
274c0 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a  b>immutable</b>:
274d0 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20   ^The immutable 
274e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
274f0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20  oolean query.** 
27500 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68      parameter th
27510 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  at indicates tha
27520 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  t the database f
27530 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e  ile is stored on
27540 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c  .**     read-onl
27550 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20  y media.  ^When 
27560 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74  immutable is set
27570 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
27580 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
27590 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63   database file c
275a0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
275b0 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63  , even by a proc
275c0 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a  ess with higher.
275d0 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65  **     privilege
275e0 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74  , and so the dat
275f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
27600 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c  read-only and al
27610 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20  l locking.**    
27620 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65   and change dete
27630 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65  ction is disable
27640 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74  d.  Caution: Set
27650 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62  ting the immutab
27660 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72  le.**     proper
27670 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ty on a database
27680 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20   file that does 
27690 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63  in fact change c
276a0 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20  an result.**    
276b0 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75   in incorrect qu
276c0 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f  ery results and/
276d0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  or [SQLITE_CORRU
276e0 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20  PT] errors..**  
276f0 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51     See also: [SQ
27700 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
27710 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20  ABLE]..**       
27720 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
27730 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
27740 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
27750 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
27760 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
27770 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
27780 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
27790 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
277a0 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
277b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
277c0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
277d0 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
277e0 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
277f0 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
27800 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
27810 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
27820 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
27830 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
27840 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
27850 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
27860 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
27870 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
27880 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
27890 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
278a0 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
278b0 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
278c0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
278d0 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
278e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
278f0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
27900 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
27910 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
27920 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
27930 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
27940 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
27950 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
27960 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
27970 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
27980 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
27990 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
279a0 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
279b0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
279c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
279d0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
279e0 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
279f0 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
27a00 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
27a10 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
27a20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
27a30 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
27a40 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
27a50 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
27a60 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
27a70 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
27a80 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
27a90 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
27aa0 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
27ab0 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
27ac0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
27ad0 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
27ae0 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
27af0 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
27b00 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
27b10 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
27b20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
27b30 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
27b40 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
27b50 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
27b60 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
27b70 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
27b80 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
27b90 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
27ba0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
27bb0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
27bc0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
27bd0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
27be0 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
27bf0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
27c00 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
27c10 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
27c20 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
27c30 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
27c40 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
27c50 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
27c60 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
27c70 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
27c80 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
27c90 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
27ca0 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
27cb0 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
27cc0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
27cd0 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
27ce0 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e  nix-dotfile <td>
27cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
27d00 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
27d10 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
27d20 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
27d30 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a   "unix-dotfile".
27d40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
27d50 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20   uses dot-files 
27d60 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69  in place of posi
27d70 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69  x advisory locki
27d80 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ng..** <tr><td> 
27d90 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
27da0 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
27db0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
27dc0 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
27dd0 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
27de0 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
27df0 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
27e00 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
27e10 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
27e20 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
27e30 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
27e40 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
27e50 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
27e60 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
27e70 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
27e80 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
27e90 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
27ea0 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
27eb0 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
27ec0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
27ed0 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
27ee0 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
27ef0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
27f00 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
27f10 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
27f20 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
27f30 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
27f40 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
27f50 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
27f60 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
27f70 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
27f80 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
27f90 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
27fa0 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
27fb0 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
27fc0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
27fd0 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
27fe0 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
27ff0 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
28000 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
28010 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
28020 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
28030 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
28040 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
28050 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
28060 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
28070 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
28080 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
28090 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
280a0 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
280b0 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
280c0 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
280d0 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
280e0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
280f0 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
28100 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
28110 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
28120 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
28130 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
28140 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
28150 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
28160 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
28170 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
28180 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
28190 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
281a0 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
281b0 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
281c0 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
281d0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
281e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
281f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
28200 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
28210 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
28220 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
28230 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
28240 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
28250 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
28260 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
28270 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
28280 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
28290 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
282a0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
282b0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
282c0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
282d0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
282e0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
282f0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
28300 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
28310 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
28320 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
28330 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
28340 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
28350 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
28360 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
28370 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
28380 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
28390 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
283a0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
283b0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
283c0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
283d0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
283e0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
283f0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
28400 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
28410 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
28420 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
28430 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
28440 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
28450 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
28460 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
28470 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
28480 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
28490 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
284a0 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
284b0 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
284c0 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
284d0 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
284e0 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
284f0 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
28500 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
28510 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
28520 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
28530 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
28540 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
28550 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
28560 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
28570 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
28580 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
28590 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
285a0 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
285b0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
285c0 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
285d0 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
285e0 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
285f0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
28600 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
28610 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
28620 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
28630 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
28640 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
28650 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
28660 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
28670 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
28680 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
28690 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
286a0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
286b0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
286c0 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
286d0 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
286e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
286f0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
28700 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
28710 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
28720 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
28730 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
28740 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
28750 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
28760 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
28770 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
28780 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
28790 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
287a0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
287b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
287c0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
287d0 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
287e0 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
287f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
28800 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
28810 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
28820 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
28830 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
28840 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
28850 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
28860 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
28870 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
28880 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
28890 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
288a0 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
288b0 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
288c0 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
288d0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
288e0 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
288f0 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
28900 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
28910 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
28920 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
28930 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
28940 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
28950 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
28960 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
28970 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
28980 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
28990 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
289a0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
289b0 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
289c0 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
289d0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
289e0 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
289f0 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
28a00 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
28a10 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
28a20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
28a30 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
28a40 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
28a50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28a60 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
28a70 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
28a80 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
28a90 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
28aa0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
28ab0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
28ac0 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
28ad0 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
28ae0 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
28af0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
28b00 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
28b10 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
28b20 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
28b30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
28b40 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
28b50 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
28b60 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
28b70 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
28b80 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
28b90 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28ba0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
28bb0 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
28bc0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
28bd0 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
28be0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
28bf0 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
28c00 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
28c10 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
28c20 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
28c30 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
28c40 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
28c50 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
28c60 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
28c70 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63  ndesirable..*/.c
28c80 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28c90 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
28ca0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
28cb0 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
28cc0 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74  ar *zParam);.int
28cd0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
28ce0 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
28cf0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
28d00 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
28d10 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74  bDefault);.sqlit
28d20 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
28d30 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
28d40 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
28d50 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
28d60 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
28d70 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
28d80 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
28d90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28da0 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
28db0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
28dc0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
28dd0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
28de0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
28df0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
28e00 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
28e10 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
28e20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
28e30 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
28e40 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
28e50 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
28e60 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
28e70 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
28e80 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
28e90 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
28ea0 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
28eb0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
28ec0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
28ed0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
28ee0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
28ef0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
28f00 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
28f10 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
28f20 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
28f30 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
28f40 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
28f50 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
28f60 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
28f70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
28f80 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
28f90 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
28fa0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
28fb0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
28fc0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
28fd0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
28fe0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
28ff0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
29000 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
29010 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
29020 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
29030 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
29040 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
29050 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
29060 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
29070 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
29080 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
29090 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
290a0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
290b0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
290c0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
290d0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
290e0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
290f0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
29100 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
29110 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
29120 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
29130 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
29140 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
29150 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29160 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
29170 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
29180 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
29190 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
291a0 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
291b0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
291c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
291d0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
291e0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
291f0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
29200 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
29210 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
29220 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
29230 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
29240 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
29250 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
29260 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
29270 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
29280 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
29290 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
292a0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
292b0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
292c0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
292d0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
292e0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
292f0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
29300 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
29310 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
29320 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
29330 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
29340 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
29350 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
29360 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
29370 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
29380 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
29390 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
293a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
293b0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
293c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
293d0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
293e0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
293f0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
29400 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
29410 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
29420 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
29430 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
29440 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
29450 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
29460 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
29470 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
29480 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
29490 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
294a0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
294b0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
294c0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
294d0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
294e0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
294f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
29500 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
29510 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
29520 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
29530 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
29540 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
29550 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
29560 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
29570 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
29580 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
29590 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
295a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
295b0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
295c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
295d0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
295e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
295f0 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
29600 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29610 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74  F: Prepared Stat
29620 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
29630 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
29640 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
29650 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29660 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
29670 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
29680 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
29690 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
296a0 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20  atement that.** 
296b0 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65  has been compile
296c0 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f  d into binary fo
296d0 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20  rm and is ready 
296e0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e  to be evaluated.
296f0 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20  .**.** Think of 
29700 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
29710 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65  nt as a separate
29720 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61   computer progra
29730 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69  m.  The.** origi
29740 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20  nal SQL text is 
29750 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20  source code.  A 
29760 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29770 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73  nt object .** is
29780 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62   the compiled ob
29790 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20  ject code.  All 
297a0 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  SQL must be conv
297b0 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20  erted into a.** 
297c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
297d0 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e  nt before it can
297e0 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   be run..**.** T
297f0 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66  he life-cycle of
29800 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
29810 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75  ement object usu
29820 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74  ally goes like t
29830 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
29840 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
29850 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
29860 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69  ement object usi
29870 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
29880 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c  are_v2()]..** <l
29890 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
298a0 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75  o [parameters] u
298b0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
298c0 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
298d0 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
298e0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
298f0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
29900 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
29910 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
29920 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
29930 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
29940 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
29950 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
29960 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
29970 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
29980 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
29990 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
299a0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
299b0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
299c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
299d0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79  ..** </ol>.*/.ty
299e0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
299f0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
29a00 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
29a10 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
29a20 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48  e Limits.** METH
29a30 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
29a40 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
29a50 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
29a60 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
29a70 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
29a80 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
29a90 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
29aa0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
29ab0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
29ac0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
29ad0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29ae0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
29af0 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
29b00 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
29b10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
29b20 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
29b30 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
29b40 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
29b50 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
29b60 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
29b70 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
29b80 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
29b90 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
29ba0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
29bb0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
29bc0 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
29bd0 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
29be0 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
29bf0 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
29c00 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
29c10 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
29c20 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
29c30 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
29c40 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
29c50 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
29c60 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
29c70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
29c80 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
29c90 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
29ca0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
29cb0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
29cc0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
29cd0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
29ce0 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
29cf0 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
29d00 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
29d10 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
29d20 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
29d30 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
29d40 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
29d50 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
29d60 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
29d70 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
29d80 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
29d90 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
29da0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
29db0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
29dc0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
29dd0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
29de0 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
29df0 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
29e00 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
29e10 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
29e20 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
29e30 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
29e40 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
29e50 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
29e60 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
29e70 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
29e80 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
29e90 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
29ea0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
29eb0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
29ec0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
29ed0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
29ee0 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
29ef0 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
29f00 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
29f10 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
29f20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
29f30 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
29f40 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
29f50 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
29f60 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
29f70 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
29f80 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
29f90 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
29fa0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
29fb0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
29fc0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
29fd0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
29fe0 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
29ff0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
2a000 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
2a010 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
2a020 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
2a030 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
2a040 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
2a050 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
2a060 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
2a070 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
2a080 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
2a090 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
2a0a0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
2a0b0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
2a0c0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
2a0d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
2a0e0 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
2a0f0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
2a100 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
2a110 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
2a120 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
2a130 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
2a140 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
2a150 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
2a160 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
2a170 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
2a180 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
2a190 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
2a1a0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
2a1b0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
2a1c0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
2a1d0 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ases..*/.int sql
2a1e0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
2a1f0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
2a200 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
2a210 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
2a220 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
2a230 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
2a240 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
2a250 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
2a260 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
2a270 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
2a280 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
2a290 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
2a2a0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
2a2b0 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
2a2c0 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
2a2d0 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
2a2e0 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
2a2f0 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
2a300 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
2a310 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
2a320 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
2a330 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
2a340 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
2a350 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
2a360 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
2a370 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
2a380 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
2a390 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a3a0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
2a3b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a3c0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
2a3d0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
2a3e0 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
2a3f0 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
2a400 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
2a410 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
2a420 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
2a430 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
2a440 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a450 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
2a460 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
2a470 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
2a480 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a490 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
2a4a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
2a4b0 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
2a4c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2a4d0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2a4e0 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
2a4f0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
2a500 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
2a510 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
2a520 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2a530 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2a540 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
2a550 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
2a560 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
2a570 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2a580 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
2a590 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
2a5a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
2a5b0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
2a5c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a5d0 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
2a5e0 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
2a5f0 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
2a600 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a610 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
2a620 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
2a630 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
2a640 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
2a650 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a660 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
2a670 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
2a680 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
2a690 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
2a6a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a6b0 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
2a6c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
2a6d0 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
2a6e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2a6f0 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
2a700 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
2a710 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
2a720 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
2a730 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
2a740 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71  atement.  If [sq
2a750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a760 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71  ()] or.** the eq
2a770 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74  uivalent tries t
2a780 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65  o allocate space
2a790 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74   for more than t
2a7a0 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73  his many opcodes
2a7b0 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20  .** in a single 
2a7c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a7d0 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f  nt, an SQLITE_NO
2a7e0 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74  MEM error is ret
2a7f0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
2a800 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a810 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
2a820 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a830 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2a840 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
2a850 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a860 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
2a870 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
2a880 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2a890 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
2a8a0 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
2a8b0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
2a8c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a8d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2a8e0 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
2a8f0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
2a900 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
2a910 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2a920 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2a930 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
2a940 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2a950 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
2a960 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a970 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
2a980 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
2a990 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
2a9a0 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
2a9b0 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
2a9c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2a9d0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2a9e0 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
2a9f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
2aa00 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
2aa10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2aa20 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
2aa30 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
2aa40 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
2aa50 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
2aa60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2aa70 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
2aa80 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2aa90 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
2aaa0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2aab0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
2aac0 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
2aad0 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
2aae0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2aaf0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
2ab00 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
2ab10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2ab20 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
2ab30 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2ab40 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
2ab50 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
2ab60 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
2ab70 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
2ab80 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
2ab90 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
2aba0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
2abb0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
2abc0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
2abd0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
2abe0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2abf0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
2ac00 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2ac10 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2ac20 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
2ac30 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
2ac40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2ac50 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
2ac60 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
2ac70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2ac80 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2ac90 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
2aca0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2acb0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
2acc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
2acd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2ace0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2acf0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
2ad00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ad10 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
2ad20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ad30 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
2ad40 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
2ad50 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
2ad60 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
2ad70 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2ad80 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
2ad90 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
2ada0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2adb0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
2adc0 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
2add0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
2ade0 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
2adf0 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
2ae00 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 20 46  I3REF: Prepare F
2ae10 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lags.**.** These
2ae20 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
2ae30 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73 20  e various flags 
2ae40 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 73 73  that can be pass
2ae50 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70  ed into.** "prep
2ae60 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65 72  Flags" parameter
2ae70 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2ae80 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 61  _prepare_v3()] a
2ae90 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
2aea0 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69  repare16_v3()] i
2aeb0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a  nterfaces..**.**
2aec0 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20 62   New flags may b
2aed0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
2aee0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
2aef0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  Lite..**.** <dl>
2af00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45  .** [[SQLITE_PRE
2af10 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 5d  PARE_PERSISTENT]
2af20 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50  ] ^(<dt>SQLITE_P
2af30 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2af40 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
2af50 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2af60 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61 67  _PERSISTENT flag
2af70 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20 74 68   is a hint to th
2af80 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 0a  e query planner.
2af90 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 70  ** that the prep
2afa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77  ared statement w
2afb0 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 64 20  ill be retained 
2afc0 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65 20  for a long time 
2afd0 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20  and.** probably 
2afe0 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69 6d 65  reused many time
2aff0 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 74 68  s.)^ ^Without th
2b000 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74 65  is flag, [sqlite
2b010 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 0a  3_prepare_v3()].
2b020 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2b030 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
2b040 61 73 73 75 6d 65 20 74 68 61 74 20 74 68 65 20  assume that the 
2b050 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b060 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20 75  nt will .** be u
2b070 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72  sed just once or
2b080 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77 20 74   at most a few t
2b090 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 64 65  imes and then de
2b0a0 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a  stroyed using.**
2b0b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b0c0 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65 6c 79  ze()] relatively
2b0d0 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72 65   soon. The curre
2b0e0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
2b0f0 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68 69  n acts.** on thi
2b100 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69 64 69  s hint by avoidi
2b110 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20 5b 6c  ng the use of [l
2b120 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 5d  ookaside memory]
2b130 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a   so as not to.**
2b140 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c 69 6d   deplete the lim
2b150 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20 6c 6f  ited store of lo
2b160 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20  okaside memory. 
2b170 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
2b180 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 79  of.** SQLite may
2b190 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68 69 6e   act on this hin
2b1a0 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a 2a  t differently..*
2b1b0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
2b1c0 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  ne SQLITE_PREPAR
2b1d0 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20 20 20  E_PERSISTENT    
2b1e0 20 20 20 20 20 20 20 20 20 20 30 78 30 31 0a 0a            0x01..
2b1f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b200 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
2b210 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
2b220 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
2b230 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
2b240 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2b250 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  te3.** CONSTRUCT
2b260 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
2b270 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
2b280 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  e an SQL stateme
2b290 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  nt, it must firs
2b2a0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
2b2b0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
2b2c0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
2b2d0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
2b2e0 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f  tines.  Or, in o
2b2f0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 73  ther words, thes
2b300 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2b310 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 20 66  e constructors f
2b320 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2b330 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
2b340 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ct..**.** The pr
2b350 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e 65 20  eferred routine 
2b360 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c 69 74  to use is [sqlit
2b370 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b380 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
2b390 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 69 6e  e3_prepare()] in
2b3a0 74 65 72 66 61 63 65 20 69 73 20 6c 65 67 61 63  terface is legac
2b3b0 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  y and should be 
2b3c0 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c  avoided..** [sql
2b3d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2b3e0 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72 61 20  )] has an extra 
2b3f0 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70 74 69  "prepFlags" opti
2b400 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65 64 0a  on that is used.
2b410 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c 20 70  ** for special p
2b420 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  urposes..**.** T
2b430 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 55 54  he use of the UT
2b440 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73 20 69  F-8 interfaces i
2b450 73 20 70 72 65 66 65 72 72 65 64 2c 20 61 73 20  s preferred, as 
2b460 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74 6c 79  SQLite currently
2b470 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61 72  .** does all par
2b480 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46 2d 38  sing using UTF-8
2b490 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e  .  The UTF-16 in
2b4a0 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
2b4b0 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f  vided.** as a co
2b4c0 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68 65 20  nvenience.  The 
2b4d0 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65  UTF-16 interface
2b4e0 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72  s work by conver
2b4f0 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75  ting the.** inpu
2b500 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54 46 2d  t text into UTF-
2b510 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67  8, then invoking
2b520 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2b530 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61  ng UTF-8 interfa
2b540 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ce..**.** The fi
2b550 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
2b560 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
2b570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
2b580 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
2b590 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
2b5a0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2b5b0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2b5c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2b5d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2b5e0 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
2b5f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b600 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
2b610 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
2b620 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
2b630 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
2b640 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
2b650 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2b660 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
2b670 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
2b680 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
2b690 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 2c  lite3_prepare(),
2b6a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b6b0 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71  _v2(),.** and sq
2b6c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2b6d0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
2b6e0 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
2b6f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b700 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  6(), sqlite3_pre
2b710 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20  pare16_v2(),.** 
2b720 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2b730 61 72 65 31 36 5f 76 33 28 29 20 75 73 65 20 55  are16_v3() use U
2b740 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
2b750 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
2b760 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ent is negative,
2b770 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
2b780 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
2b790 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2b7a0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
2b7b0 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
2b7c0 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20  en it is the.** 
2b7d0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2b7e0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
2b7f0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65   ^If nByte is ze
2b800 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70  ro, then no prep
2b810 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2b820 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a  t is generated..
2b830 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  ** If the caller
2b840 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20   knows that the 
2b850 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
2b860 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
2b870 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65  d, then.** there
2b880 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66   is a small perf
2b890 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
2b8a0 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20  e to passing an 
2b8b0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
2b8c0 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e  that.** is the n
2b8d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2b8e0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
2b8f0 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
2b900 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
2b910 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
2b920 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
2b930 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
2b940 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
2b950 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
2b960 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
2b970 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
2b980 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
2b990 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
2b9a0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
2b9b0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
2b9c0 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
2b9d0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
2b9e0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
2b9f0 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
2ba00 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
2ba10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
2ba20 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
2ba30 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
2ba40 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
2ba50 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
2ba60 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
2ba70 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
2ba80 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
2ba90 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
2baa0 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
2bab0 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
2bac0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
2bad0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
2bae0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
2baf0 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
2bb00 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
2bb10 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
2bb20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
2bb30 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
2bb40 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
2bb50 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
2bb60 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
2bb70 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
2bb80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2bb90 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
2bba0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
2bbb0 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
2bbc0 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
2bbd0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
2bbe0 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
2bbf0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
2bc00 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
2bc10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2bc20 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
2bc30 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
2bc40 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
2bc50 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2bc60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c 20 73  _prepare_v2(), s
2bc70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bc80 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  3(), sqlite3_pre
2bc90 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20  pare16_v2(),.** 
2bca0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2bcb0 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74 65 72  are16_v3() inter
2bcc0 66 61 63 65 73 20 61 72 65 20 72 65 63 6f 6d 6d  faces are recomm
2bcd0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
2bce0 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54  w programs..** T
2bcf0 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  he older interfa
2bd00 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70 72 65  ces (sqlite3_pre
2bd10 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
2bd20 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 29 0a  e3_prepare16()).
2bd30 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ** are retained 
2bd40 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
2bd50 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
2bd60 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
2bd70 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
2bd80 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72  n the "vX" inter
2bd90 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
2bda0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2bdb0 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
2bdc0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2bdd0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
2bde0 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
2bdf0 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
2be00 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
2be10 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
2be20 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
2be30 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
2be40 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
2be50 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
2be60 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2be70 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
2be80 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
2be90 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
2bea0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2beb0 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
2bec0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
2bed0 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
2bee0 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
2bef0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2bf00 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
2bf10 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
2bf20 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
2bf30 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
2bf40 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
2bf50 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
2bf60 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
2bf70 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
2bf80 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
2bf90 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
2bfa0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2bfb0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
2bfc0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
2bfd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2bfe0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
2bff0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
2c000 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
2c010 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
2c020 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
2c030 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2c040 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
2c050 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c060 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
2c070 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
2c080 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
2c090 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
2c0a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
2c0b0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
2c0c0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
2c0d0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2c0e0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
2c0f0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
2c100 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
2c110 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
2c120 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
2c130 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
2c140 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
2c150 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
2c160 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2c170 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
2c180 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2c190 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
2c1a0 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
2c1b0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
2c1c0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
2c1d0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
2c1e0 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
2c1f0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
2c200 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2c210 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
2c220 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
2c230 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2c240 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
2c250 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
2c260 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
2c270 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
2c280 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
2c290 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
2c2a0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
2c2b0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
2c2c0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
2c2d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
2c2e0 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
2c2f0 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
2c300 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
2c310 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
2c320 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
2c330 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
2c340 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
2c350 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
2c360 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2c370 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
2c380 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
2c390 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
2c3a0 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
2c3b0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
2c3c0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
2c3d0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
2c3e0 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
2c3f0 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
2c400 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2c410 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
2c420 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e   </li>.**.** <p>
2c430 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  ^sqlite3_prepare
2c440 5f 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72  _v3() differs fr
2c450 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  om sqlite3_prepa
2c460 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20  re_v2() only in 
2c470 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78  having.** the ex
2c480 74 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61  tra prepFlags pa
2c490 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69  rameter, which i
2c4a0 73 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f  s a bit array co
2c4b0 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f  nsisting of zero
2c4c0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74   or.** more of t
2c4d0 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41  he [SQLITE_PREPA
2c4e0 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51  RE_PERSISTENT|SQ
2c4f0 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20  LITE_PREPARE_*] 
2c500 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20  flags.  ^The.** 
2c510 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c520 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
2c530 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65  orks exactly the
2c540 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
2c550 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2c560 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65   with a zero pre
2c570 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72  pFlags parameter
2c580 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  ..** </ol>.*/.in
2c590 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2c5a0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2c5b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2c5c0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2c5d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c5e0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2c5f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2c600 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2c610 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2c620 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2c630 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2c640 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2c650 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2c660 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2c670 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2c680 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2c690 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2c6a0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2c6b0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2c6c0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2c6d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2c6e0 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
2c6f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2c700 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2c710 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c720 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2c730 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2c740 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2c750 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2c760 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2c770 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2c780 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2c790 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2c7a0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2c7b0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2c7c0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2c7d0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2c7e0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2c7f0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2c800 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2c810 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2c820 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 0a 20  e3_prepare_v3(. 
2c830 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2c840 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2c850 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2c860 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2c870 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2c880 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2c890 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2c8a0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2c8b0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2c8c0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2c8d0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75  in bytes. */.  u
2c8e0 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70  nsigned int prep
2c8f0 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f  Flags, /* Zero o
2c900 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52  r more SQLITE_PR
2c910 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a  EPARE_ flags */.
2c920 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2c930 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2c940 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2c950 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2c960 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2c970 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2c980 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2c990 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2c9a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2c9b0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
2c9c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2c9d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2c9e0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2c9f0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2ca00 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2ca10 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2ca20 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2ca30 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2ca40 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2ca50 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2ca60 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2ca70 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2ca80 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2ca90 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2caa0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2cab0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2cac0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2cad0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2cae0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2caf0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
2cb00 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2cb10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2cb20 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2cb30 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2cb40 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2cb50 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2cb60 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2cb70 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2cb80 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2cb90 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2cba0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2cbb0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2cbc0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2cbd0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2cbe0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2cbf0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2cc00 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2cc10 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2cc20 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2cc30 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2cc40 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c 69 74  re16_v3(.  sqlit
2cc50 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2cc60 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2cc70 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2cc80 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2cc90 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2cca0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2ccb0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2ccc0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2ccd0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2cce0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2ccf0 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e  tes. */.  unsign
2cd00 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73  ed int prepFlags
2cd10 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72  , /* Zero or mor
2cd20 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2cd30 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c  _ flags */.  sql
2cd40 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2cd50 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2cd60 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2cd70 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2cd80 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2cd90 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2cda0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2cdb0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
2cdc0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
2cdd0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
2cde0 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   SQL.** METHOD: 
2cdf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2ce00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ce10 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2ce20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2ce30 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20  er to a copy of 
2ce40 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c  the UTF-8.** SQL
2ce50 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
2ce60 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73  eate [prepared s
2ce70 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50  tatement] P if P
2ce80 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20   was.** created 
2ce90 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
2cea0 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2ceb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2cec0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
2ced0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20  repare16_v2()], 
2cee0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2cef0 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20  are16_v3()]..** 
2cf00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70  ^The sqlite3_exp
2cf10 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74  anded_sql(P) int
2cf20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2cf30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54   pointer to a UT
2cf40 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  F-8.** string co
2cf50 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c  ntaining the SQL
2cf60 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65   text of prepare
2cf70 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69  d statement P wi
2cf80 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72  th.** [bound par
2cf90 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65  ameters] expande
2cfa0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2cfb0 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65  xample, if a pre
2cfc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2cfd0 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
2cfe0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74   the SQL.** text
2cff0 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78   "SELECT $abc,:x
2d000 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d  yz" and if param
2d010 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75  eter $abc is bou
2d020 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33  nd to integer 23
2d030 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65  45.** and parame
2d040 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f  ter :xyz is unbo
2d050 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  und, then sqlite
2d060 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74  3_sql() will ret
2d070 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  urn.** the origi
2d080 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c  nal string, "SEL
2d090 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62  ECT $abc,:xyz" b
2d0a0 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  ut sqlite3_expan
2d0b0 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c  ded_sql().** wil
2d0c0 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54  l return "SELECT
2d0d0 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a   2345,NULL".)^.*
2d0e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d0f0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2d100 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d110 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  ns NULL if insuf
2d120 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a  ficient memory.*
2d130 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74  * is available t
2d140 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
2d150 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73  t, or if the res
2d160 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64  ult would exceed
2d170 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69   the.** the maxi
2d180 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74  mum string lengt
2d190 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  h determined by 
2d1a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  the [SQLITE_LIMI
2d1b0 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a  T_LENGTH]..**.**
2d1c0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52   ^The [SQLITE_TR
2d1d0 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
2d1e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2d1f0 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73  ion limits the s
2d200 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20  ize of.** bound 
2d210 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73  parameter expans
2d220 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c  ions.  ^The [SQL
2d230 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20  ITE_OMIT_TRACE] 
2d240 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
2d250 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71  option causes sq
2d260 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2d270 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72  ql() to always r
2d280 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  eturn NULL..**.*
2d290 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65  * ^The string re
2d2a0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2d2b0 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e 61  3_sql(P) is mana
2d2c0 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 6e  ged by SQLite an
2d2d0 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  d is.** automati
2d2e0 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e  cally freed when
2d2f0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2d300 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2d310 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74  ized..** ^The st
2d320 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
2d330 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2d340 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65  d_sql(P), on the
2d350 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20   other hand,.** 
2d360 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  is obtained from
2d370 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2d380 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20  ()] and must be 
2d390 66 72 65 65 20 62 79 20 74 68 65 20 61 70 70 6c  free by the appl
2d3a0 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61  ication.** by pa
2d3b0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
2d3c0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f  ite3_free()]..*/
2d3d0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2d3e0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
2d3f0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63  _stmt *pStmt);.c
2d400 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78 70  har *sqlite3_exp
2d410 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74 65  anded_sql(sqlite
2d420 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2d430 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d440 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
2d450 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
2d460 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
2d470 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  se.** METHOD: sq
2d480 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2d490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2d4a0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
2d4b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d4c0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2d4d0 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
2d4e0 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
2d4f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
2d500 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
2d510 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
2d520 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2d530 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
2d540 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
2d550 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d560 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2d570 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
2d580 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
2d590 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2d5a0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
2d5b0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
2d5c0 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
2d5d0 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
2d5e0 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
2d5f0 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
2d600 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
2d610 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2d620 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
2d630 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
2d640 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
2d650 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2d660 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
2d670 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
2d680 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
2d690 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
2d6a0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
2d6b0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
2d6c0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
2d6d0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
2d6e0 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
2d6f0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2d700 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2d710 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2d720 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
2d730 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2d740 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
2d750 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
2d760 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
2d770 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
2d780 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
2d790 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
2d7a0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
2d7b0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
2d7c0 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
2d7d0 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
2d7e0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2d7f0 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
2d800 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
2d810 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
2d820 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
2d830 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2d840 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
2d850 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
2d860 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
2d870 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
2d880 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
2d890 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
2d8a0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
2d8b0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
2d8c0 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
2d8d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2d8e0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2d8f0 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
2d900 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
2d910 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
2d920 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
2d930 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
2d940 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
2d950 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
2d960 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
2d970 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
2d980 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
2d990 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  disk..** ^The sq
2d9a0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2d9b0 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  nly() interface 
2d9c0 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f 72  returns true for
2d9d0 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a   [BEGIN] since.*
2d9e0 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79  * [BEGIN] merely
2d9f0 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20 66   sets internal f
2da00 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b 42  lags, but the [B
2da10 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44  EGIN|BEGIN IMMED
2da20 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45  IATE] and.** [BE
2da30 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55 53  GIN|BEGIN EXCLUS
2da40 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f  IVE] commands do
2da50 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61 62   touch the datab
2da60 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71  ase and so.** sq
2da70 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2da80 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66 61  nly() returns fa
2da90 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63 6f  lse for those co
2daa0 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73  mmands..*/.int s
2dab0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2dac0 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
2dad0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2dae0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
2daf0 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
2db00 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
2db10 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20  s Been Reset.** 
2db20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2db30 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2db40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2db50 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
2db60 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2db70 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
2db80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2db90 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
2dba0 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
2dbb0 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
2dbc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2dbd0 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68  )] but has neith
2dbe0 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  er run to comple
2dbf0 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a  tion (returned.*
2dc00 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20  * [SQLITE_DONE] 
2dc10 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74  from [sqlite3_st
2dc20 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62  ep(S)]) nor.** b
2dc30 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
2dc40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2dc50 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
2dc60 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
2dc70 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2dc80 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
2dc90 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2dca0 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
2dcb0 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
2dcc0 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
2dcd0 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
2dce0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
2dcf0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2dd00 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2dd10 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2dd20 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
2dd30 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
2dd40 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2dd50 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
2dd60 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
2dd70 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
2dd80 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
2dd90 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
2dda0 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
2ddb0 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
2ddc0 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
2ddd0 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
2dde0 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
2ddf0 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
2de00 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
2de10 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
2de20 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
2de30 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
2de40 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
2de50 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
2de60 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
2de70 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  open..*/.int sql
2de80 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
2de90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2dea0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2deb0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
2dec0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
2ded0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
2dee0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2def0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
2df00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2df10 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
2df20 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
2df30 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
2df40 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
2df50 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
2df60 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
2df70 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
2df80 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2df90 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
2dfa0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
2dfb0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
2dfc0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
2dfd0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2dfe0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
2dff0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
2e000 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
2e010 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
2e020 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
2e030 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e040 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
2e050 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
2e060 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
2e070 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
2e080 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
2e090 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e0a0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
2e0b0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
2e0c0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
2e0d0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
2e0e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2e0f0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
2e100 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
2e110 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
2e120 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
2e130 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
2e140 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
2e150 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
2e160 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e170 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  lue.  The.** [sq
2e180 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2e190 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2e1a0 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   be used to cons
2e1b0 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20  truct a new .** 
2e1c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e1d0 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20  3_value from an 
2e1e0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e1f0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
2e200 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
2e210 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
2e220 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
2e230 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
2e240 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
2e250 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
2e260 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
2e270 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
2e280 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e290 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
2e2a0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2e2b0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
2e2c0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e2d0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
2e2e0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
2e2f0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
2e300 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
2e310 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2e320 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
2e330 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2e340 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
2e350 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
2e360 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
2e370 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
2e380 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
2e390 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2e3a0 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
2e3b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2e3c0 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
2e3d0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
2e3e0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2e3f0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2e400 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2e410 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2e420 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
2e430 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
2e440 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
2e450 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
2e460 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
2e470 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
2e480 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
2e490 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
2e4a0 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
2e4b0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2e4c0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2e4d0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e4e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
2e4f0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
2e500 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
2e510 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e520 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e530 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
2e540 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
2e550 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
2e560 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
2e570 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e580 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2e590 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
2e5a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e5b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
2e5c0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2e5d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2e5e0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
2e5f0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
2e600 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e610 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
2e620 6c 79 20 62 65 20 75 73 65 64 20 61 73 20 61 72  ly be used as ar
2e630 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73  guments.** to [s
2e640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2e650 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lue()], [sqlite3
2e660 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2c 20  _bind_value()], 
2e670 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2e680 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a  value_dup()]..**
2e690 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2e6a0 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
2e6b0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
2e6c0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
2e6d0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2e6e0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2e6f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e700 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2e710 75 63 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  uct sqlite3_valu
2e720 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  e sqlite3_value;
2e730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e740 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
2e750 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
2e760 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
2e770 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
2e780 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
2e790 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
2e7a0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
2e7b0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
2e7c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
2e7d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2e7e0 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
2e7f0 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
2e800 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
2e810 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2e820 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
2e830 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2e840 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2e850 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2e860 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
2e870 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
2e880 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
2e890 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
2e8a0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
2e8b0 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
2e8c0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2e8d0 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
2e8e0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2e8f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2e900 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2e910 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
2e920 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
2e930 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
2e940 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
2e950 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2e960 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
2e970 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
2e980 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
2e990 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
2e9a0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
2e9b0 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
2e9c0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
2e9d0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
2e9e0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
2e9f0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2ea00 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2ea10 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
2ea20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
2ea30 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
2ea40 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ng}.** METHOD: s
2ea50 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ea60 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
2ea70 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
2ea80 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
2ea90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2eaa0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
2eab0 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
2eac0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
2ead0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
2eae0 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
2eaf0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
2eb00 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
2eb10 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
2eb20 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
2eb30 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
2eb40 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
2eb50 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
2eb60 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
2eb70 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
2eb80 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
2eb90 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
2eba0 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
2ebb0 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
2ebc0 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
2ebd0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
2ebe0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
2ebf0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
2ec00 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
2ec10 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
2ec20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
2ec30 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
2ec40 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2ec50 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2ec60 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
2ec70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2ec80 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2ec90 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2eca0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
2ecb0 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
2ecc0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
2ecd0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2ece0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
2ecf0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2ed00 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
2ed10 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
2ed20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2ed30 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2ed40 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
2ed50 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
2ed60 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
2ed70 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
2ed80 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2ed90 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
2eda0 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
2edb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
2edc0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
2edd0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
2ede0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
2edf0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
2ee00 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
2ee10 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
2ee20 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
2ee30 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
2ee40 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
2ee50 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
2ee60 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
2ee70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2ee80 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
2ee90 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
2eea0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
2eeb0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
2eec0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
2eed0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
2eee0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
2eef0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
2ef00 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
2ef10 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
2ef20 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2ef30 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
2ef40 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
2ef50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2ef60 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2ef70 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
2ef80 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2ef90 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
2efa0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2efb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2efc0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2efd0 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2efe0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2eff0 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
2f000 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
2f010 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f020 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
2f030 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
2f040 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
2f050 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
2f060 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
2f070 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
2f080 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
2f090 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
2f0a0 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
2f0b0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2f0c0 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
2f0d0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
2f0e0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
2f0f0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2f100 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
2f110 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
2f120 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2f130 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
2f140 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2f150 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f160 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2f170 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f180 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
2f190 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2f1a0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2f1b0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2f1c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2f1d0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2f1e0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2f1f0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
2f200 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2f210 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f220 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
2f230 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
2f240 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2f250 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
2f260 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
2f270 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
2f280 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
2f290 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
2f2a0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f2b0 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74  ext16() or sqlit
2f2c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2f2d0 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61   then.** that pa
2f2e0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2f2f0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
2f300 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
2f310 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
2f320 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
2f330 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
2f340 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
2f350 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
2f360 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
2f370 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
2f380 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
2f390 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2f3a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2f3b0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2f3c0 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
2f3d0 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
2f3e0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
2f3f0 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
2f400 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
2f410 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
2f420 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
2f430 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
2f440 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
2f450 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
2f460 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e  e BLOB and strin
2f470 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66  g binding interf
2f480 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73  aces.** is a des
2f490 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
2f4a0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2f4b0 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
2f4c0 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
2f4d0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2f4e0 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
2f4f0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
2f500 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
2f510 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2f520 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
2f530 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20  all to bind API 
2f540 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  fails..** ^If th
2f550 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2f560 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
2f570 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
2f580 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
2f590 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2f5a0 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
2f5b0 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
2f5c0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
2f5d0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2f5e0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
2f5f0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
2f600 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
2f610 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
2f620 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
2f630 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
2f640 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
2f650 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2f660 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
2f670 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
2f680 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2f690 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2f6a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ..**.** ^The six
2f6b0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2f6c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f6d0 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  64() must be one
2f6e0 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   of.** [SQLITE_U
2f6f0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2f700 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
2f710 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
2f720 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74  TE_UTF16LE].** t
2f730 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e  o specify the en
2f740 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65  coding of the te
2f750 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  xt in the third 
2f760 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a  parameter.  If.*
2f770 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75  * the sixth argu
2f780 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2f790 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73  bind_text64() is
2f7a0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
2f7b0 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  ** allowed value
2f7c0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f  s shown above, o
2f7d0 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e  r if the text en
2f7e0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2f7f0 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ent.** from the 
2f800 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2f810 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20  ed by the sixth 
2f820 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
2f830 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2f840 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2f850 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f860 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
2f870 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
2f880 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
2f890 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
2f8a0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
2f8b0 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
2f8c0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
2f8d0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
2f8e0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
2f8f0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
2f900 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
2f910 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
2f920 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
2f930 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
2f940 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
2f950 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
2f960 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
2f970 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
2f980 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2f990 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
2f9a0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
2f9b0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
2f9c0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
2f9d0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
2f9e0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
2f9f0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
2fa00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fa10 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
2fa20 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f 75 74  (S,I,P,T,D) rout
2fa30 69 6e 65 20 63 61 75 73 65 73 20 74 68 65 20 49  ine causes the I
2fa40 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e  -th parameter in
2fa50 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2fa60 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 68 61  atement] S to ha
2fa70 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75 65 20  ve an SQL value 
2fa80 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74 6f 20  of NULL, but to 
2fa90 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73 6f 63  also be.** assoc
2faa0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
2fab0 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79 70 65  ointer P of type
2fac0 20 54 2e 20 20 5e 44 20 69 73 20 65 69 74 68 65   T.  ^D is eithe
2fad0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
2fae0 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72   or.** a pointer
2faf0 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72   to a destructor
2fb00 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 50 2e   function for P.
2fb10 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e   ^SQLite will in
2fb20 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65 73 74  voke the.** dest
2fb30 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20  ructor D with a 
2fb40 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
2fb50 6f 66 20 50 20 77 68 65 6e 20 69 74 20 69 73 20  of P when it is 
2fb60 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a  finished using.*
2fb70 2a 20 50 2e 20 20 54 68 65 20 54 20 70 61 72 61  * P.  The T para
2fb80 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
2fb90 61 20 73 74 61 74 69 63 20 73 74 72 69 6e 67 2c  a static string,
2fba0 20 70 72 65 66 65 72 61 62 6c 79 20 61 20 73 74   preferably a st
2fbb0 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e  ring.** literal.
2fbc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
2fbd0 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 74  d_pointer() rout
2fbe0 69 6e 65 20 69 73 20 70 61 72 74 20 6f 66 20 74  ine is part of t
2fbf0 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72 20 70  he.** [pointer p
2fc00 61 73 73 69 6e 67 20 69 6e 74 65 72 66 61 63 65  assing interface
2fc10 5d 20 61 64 64 65 64 20 66 6f 72 20 53 51 4c 69  ] added for SQLi
2fc20 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a  te 3.20.0..**.**
2fc30 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2fc40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2fc50 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2fc60 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2fc70 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2fc80 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2fc90 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2fca0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2fcb0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2fcc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2fcd0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2fce0 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2fcf0 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2fd00 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2fd10 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2fd20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2fd30 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2fd40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2fd50 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2fd60 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2fd70 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2fd80 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2fd90 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2fda0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2fdb0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2fdc0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2fdd0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2fde0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2fdf0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2fe00 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2fe10 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2fe20 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2fe30 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2fe40 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2fe50 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2fe60 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2fe70 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2fe80 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2fe90 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2fea0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2feb0 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
2fec0 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
2fed0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
2fee0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
2fef0 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
2ff00 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
2ff10 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2ff20 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
2ff30 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
2ff40 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
2ff50 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2ff60 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2ff70 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2ff80 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2ff90 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2ffa0 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2ffb0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2ffc0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2ffd0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2ffe0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2fff0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
30000 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30010 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
30020 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30030 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
30040 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30050 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
30060 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
30070 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
30080 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
30090 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
300a0 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69  bind_blob64(sqli
300b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
300c0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c  const void*, sql
300d0 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
300e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
300f0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
30100 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
30110 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
30120 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30130 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
30140 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
30150 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30160 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
30170 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
30180 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30190 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
301a0 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
301b0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
301c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
301d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
301e0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
301f0 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
30200 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
30210 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
30220 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
30230 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30240 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
30250 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
30260 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
30270 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
30280 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30290 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
302a0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
302b0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
302c0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
302d0 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
302e0 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
302f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
30300 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
30310 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
30320 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
30330 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
30340 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 73 71  _bind_pointer(sq
30350 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30360 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  , void*, const c
30370 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76 6f 69  har*,void(*)(voi
30380 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
30390 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
303a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
303b0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20  nt, int n);.int 
303c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
303d0 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  oblob64(sqlite3_
303e0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
303f0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a  te3_uint64);../*
30400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
30410 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
30420 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
30430 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30440 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
30450 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
30460 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
30470 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
30480 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
30490 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
304a0 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
304b0 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
304c0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
304d0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
304e0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
304f0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
30500 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
30510 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
30520 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
30530 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
30540 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
30550 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
30560 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
30570 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
30580 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
30590 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
305a0 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
305b0 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
305c0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
305d0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
305e0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
305f0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
30600 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
30610 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
30620 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
30630 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
30640 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
30650 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
30660 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
30670 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
30680 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
30690 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
306a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
306b0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
306c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
306d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
306e0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
306f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30700 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
30710 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
30720 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
30730 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
30740 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meter.** METHOD:
30750 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30760 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30770 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30780 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
30790 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
307a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
307b0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
307c0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
307d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
307e0 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
307f0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
30800 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
30810 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
30820 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
30830 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
30840 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
30850 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
30860 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
30870 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
30880 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
30890 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
308a0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
308b0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
308c0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
308d0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
308e0 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
308f0 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
30900 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
30910 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
30920 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
30930 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
30940 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
30950 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
30960 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
30970 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
30980 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
30990 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
309a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
309b0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
309c0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
309d0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
309e0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
309f0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
30a00 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
30a10 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
30a20 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
30a30 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
30a40 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
30a50 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
30a60 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
30a70 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
30a80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30a90 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  e16()],.** [sqli
30aa0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
30ab0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
30ac0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
30ad0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
30ae0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
30af0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
30b00 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
30b10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30b20 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
30b30 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
30b40 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
30b50 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
30b60 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
30b70 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
30b80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30b90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
30ba0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
30bb0 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
30bc0 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d   Given Name.** M
30bd0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
30be0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
30bf0 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
30c00 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
30c10 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
30c20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
30c30 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
30c40 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
30c50 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
30c60 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
30c70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
30c80 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
30c90 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
30ca0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
30cb0 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
30cc0 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
30cd0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
30ce0 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
30cf0 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
30d00 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
30d10 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
30d20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
30d30 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
30d40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
30d50 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 0a  pare16_v2()] or.
30d60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
30d70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a  are16_v3()]..**.
30d80 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
30d90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
30da0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
30db0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30dc0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
30dd0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
30de0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30df0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f  eter_name()]..*/
30e00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30e10 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
30e20 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
30e30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
30e40 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
30e50 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
30e60 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
30e70 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
30e80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
30e90 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30ea0 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
30eb0 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
30ec0 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
30ed0 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
30ee0 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
30ef0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
30f00 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
30f10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30f20 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
30f30 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
30f40 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
30f50 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
30f60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
30f70 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
30f80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
30f90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
30fa0 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
30fb0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
30fc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
30fd0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30fe0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
30ff0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
31000 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
31010 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
31020 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
31030 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73  ement]. ^If this
31040 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31050 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74   0, that means t
31060 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  he .** [prepared
31070 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75   statement] retu
31080 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72  rns no data (for
31090 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
310a0 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76  ATE])..** ^Howev
310b0 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65  er, just because
310c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
310d0 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65  turns a positive
310e0 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74   number does not
310f0 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e  .** mean that on
31100 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f  e or more rows o
31110 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72  f data will be r
31120 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c  eturned.  ^A SEL
31130 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  ECT statement.**
31140 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76   will always hav
31150 65 20 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c  e a positive sql
31160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
31170 74 28 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e  t() but dependin
31180 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52  g on the.** WHER
31190 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
311a0 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61 62  ints and the tab
311b0 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d  le content, it m
311c0 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72  ight return no r
311d0 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ows..**.** See a
311e0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
311f0 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
31200 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
31210 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
31220 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
31230 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
31240 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
31250 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
31260 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31270 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
31280 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
31290 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
312a0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
312b0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
312c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
312d0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
312e0 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
312f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
31300 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
31310 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
31320 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
31330 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
31340 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
31350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
31360 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
31370 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
31380 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
31390 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
313a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
313b0 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
313c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
313d0 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
313e0 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
313f0 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
31400 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
31410 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
31420 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
31430 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
31440 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
31450 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
31460 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
31470 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
31480 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
31490 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
314a0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
314b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
314c0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
314d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
314e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
314f0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
31500 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
31510 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
31520 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
31530 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
31540 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
31550 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
31560 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
31570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
31580 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
31590 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
315a0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
315b0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
315c0 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
315d0 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
315e0 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
315f0 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
31600 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
31610 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
31620 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
31630 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
31640 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
31650 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
31660 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
31670 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
31680 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
31690 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
316a0 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
316b0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
316c0 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
316d0 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
316e0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
316f0 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
31700 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
31710 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
31720 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
31730 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
31740 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
31750 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
31760 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
31770 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
31790 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
317a0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
317b0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
317c0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
317d0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
317e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
317f0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
31800 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
31810 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
31820 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
31830 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
31840 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
31850 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
31860 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
31870 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
31880 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
31890 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
318a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
318b0 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
318c0 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
318d0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
318e0 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
318f0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
31900 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
31910 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
31920 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
31930 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
31940 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
31950 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
31960 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
31970 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
31980 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
31990 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
319a0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
319b0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
319c0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
319d0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
319e0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
319f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31a00 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
31a10 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
31a20 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
31a30 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
31a40 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
31a50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
31a60 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
31a70 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
31a80 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
31a90 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
31aa0 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
31ab0 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
31ac0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
31ad0 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
31ae0 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
31af0 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
31b00 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
31b10 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
31b20 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
31b30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
31b40 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
31b50 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
31b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
31b70 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
31b80 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
31b90 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
31ba0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
31bb0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
31bc0 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
31bd0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
31be0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
31bf0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
31c00 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
31c10 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
31c20 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
31c30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
31c40 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
31c50 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
31c60 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
31c70 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
31c80 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
31c90 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
31ca0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
31cb0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
31cc0 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
31cd0 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
31ce0 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
31cf0 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
31d00 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
31d10 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
31d20 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
31d30 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
31d40 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
31d50 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
31d60 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
31d70 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
31d80 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
31d90 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
31da0 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
31db0 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
31dc0 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
31dd0 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
31de0 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
31df0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
31e00 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
31e10 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
31e20 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
31e30 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
31e40 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
31e50 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
31e60 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
31e70 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
31e80 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
31e90 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
31ea0 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
31eb0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
31ec0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
31ed0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
31ee0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
31ef0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
31f00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31f10 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
31f20 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
31f30 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
31f40 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
31f50 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
31f60 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
31f70 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
31f80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
31f90 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
31fa0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
31fb0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
31fc0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
31fd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31fe0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
31ff0 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
32000 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
32010 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
32020 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
32030 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
32040 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
32050 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
32060 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
32070 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
32080 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
32090 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
320a0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
320b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
320c0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
320d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
320e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
320f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
32100 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
32110 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
32120 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32130 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
32140 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
32150 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
32160 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
32170 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
32180 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32190 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
321a0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
321b0 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
321c0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
321d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
321e0 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
321f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
32200 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
32210 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
32220 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
32230 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
32240 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
32250 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
32260 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
32270 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
32280 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
32290 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
322a0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
322b0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
322c0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
322d0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
322e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
322f0 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
32300 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
32310 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
32320 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
32330 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
32340 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
32350 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
32360 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
32370 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
32380 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
32390 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
323a0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
323b0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
323c0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
323d0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
323e0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
323f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
32400 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
32410 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
32420 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
32430 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
32440 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
32450 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
32460 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
32470 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
32480 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
32490 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
324a0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
324b0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
324c0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
324d0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
324e0 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
324f0 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
32500 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
32510 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
32520 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
32530 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
32540 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
32550 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
32560 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
32570 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
32580 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
32590 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
325a0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
325b0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
325c0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
325d0 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
325e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
325f0 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
32600 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
32610 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
32620 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
32630 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
32640 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32650 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
32660 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32670 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
32680 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
32690 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
326a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
326b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
326c0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
326d0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
326e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
326f0 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
32700 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32710 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
32720 65 70 61 72 65 64 20 75 73 69 6e 67 20 61 6e 79  epared using any
32730 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
32740 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
32750 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
32760 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v3()], [sqlite3_
32770 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
32780 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
32790 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
327a0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
327b0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
327c0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
327d0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
327e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
327f0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
32800 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
32810 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
32820 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
32830 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
32840 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
32850 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
32860 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
32870 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
32880 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
32890 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
328a0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
328b0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
328c0 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 0a  "vX" interfaces.
328d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
328e0 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69  are_v3()], [sqli
328f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
32900 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
32910 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20  are16_v3()],.** 
32920 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32930 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
32940 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
32950 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
32960 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
32970 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
32980 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
32990 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
329a0 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 20   "vX" interface 
329b0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
329c0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
329d0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
329e0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
329f0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
32a00 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
32a10 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
32a20 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
32a30 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
32a40 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
32a50 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
32a60 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
32a70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
32a80 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
32a90 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
32aa0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
32ab0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
32ac0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
32ad0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
32ae0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
32af0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
32b00 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
32b10 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
32b20 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
32b30 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
32b40 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
32b50 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
32b60 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
32b70 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
32b80 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
32b90 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
32ba0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
32bb0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
32bc0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
32bd0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
32be0 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
32bf0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
32c00 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
32c10 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
32c20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
32c30 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
32c40 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
32c50 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
32c60 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
32c70 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
32c80 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
32c90 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
32ca0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
32cb0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
32cc0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
32cd0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
32ce0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
32cf0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
32d00 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
32d10 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
32d20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
32d30 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
32d40 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
32d50 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
32d60 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
32d70 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
32d80 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
32d90 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
32da0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
32db0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
32dc0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
32dd0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
32de0 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
32df0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
32e00 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
32e10 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
32e20 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
32e30 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
32e40 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
32e50 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
32e60 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
32e70 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
32e80 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
32e90 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
32ea0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
32eb0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
32ec0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
32ed0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
32ee0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
32ef0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
32f00 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
32f10 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
32f20 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
32f30 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
32f40 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
32f50 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
32f60 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
32f70 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
32f80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
32f90 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
32fa0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
32fb0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
32fc0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
32fd0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
32fe0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
32ff0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
33000 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
33010 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
33020 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
33030 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
33040 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
33050 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
33060 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
33070 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
33080 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
33090 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
330a0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
330b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
330c0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
330d0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
330e0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
330f0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
33100 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
33110 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
33120 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
33130 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
33140 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
33150 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
33160 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
33170 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
33180 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
33190 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
331a0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
331b0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
331c0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
331d0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
331e0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
331f0 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
33200 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
33210 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
33220 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
33230 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
33240 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
33250 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
33260 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
33270 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
33280 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
33290 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
332a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
332b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
332c0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
332d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
332e0 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
332f0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
33300 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
33310 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
33320 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
33330 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
33340 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
33350 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
33360 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
33370 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
33380 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
33390 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
333a0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
333b0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
333c0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
333d0 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e  fter [version 3.
333e0 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66  6.23.1] ([dateof
333f0 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73  :3.6.23.1],.** s
33400 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
33410 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
33420 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33430 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
33440 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
33450 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
33460 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
33470 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
33480 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
33490 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
334a0 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
334b0 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
334c0 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
334d0 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
334e0 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
334f0 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
33500 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
33510 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
33520 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
33530 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
33540 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
33550 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
33560 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
33570 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
33580 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
33590 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
335a0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
335b0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
335c0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
335d0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
335e0 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
335f0 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
33600 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
33610 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
33620 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
33630 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
33640 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
33650 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33660 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
33670 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
33680 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
33690 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
336a0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
336b0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
336c0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
336d0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
336e0 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
336f0 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
33700 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
33710 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
33720 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
33730 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
33740 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
33750 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
33760 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
33770 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f 72 20  repare_v3()] or 
33780 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33790 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  _v2()].** or [sq
337a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
337b0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
337c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
337d0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
337e0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
337f0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
33800 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
33810 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
33820 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
33830 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
33840 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
33850 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
33860 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
33870 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
33880 65 20 6f 66 20 74 68 65 20 22 76 58 22 20 69 6e  e of the "vX" in
33890 74 65 72 66 61 63 65 73 20 69 73 20 72 65 63 6f  terfaces is reco
338a0 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
338b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
338c0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
338d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
338e0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
338f0 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
33900 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
33910 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
33920 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
33930 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
33940 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
33950 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
33960 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
33970 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
33980 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
33990 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
339a0 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
339b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
339c0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
339d0 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
339e0 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
339f0 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
33a00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
33a10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33a20 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
33a30 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
33a40 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33a50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
33a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
33a70 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
33a80 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
33a90 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
33aa0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
33ab0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
33ac0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
33ad0 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
33ae0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
33af0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
33b00 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
33b10 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
33b20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
33b30 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
33b40 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
33b50 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
33b60 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
33b70 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
33b80 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
33b90 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
33ba0 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
33bb0 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
33bc0 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
33bd0 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
33be0 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
33bf0 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
33c00 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
33c10 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
33c20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
33c30 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
33c40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
33c50 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
33c60 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
33c70 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
33c80 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
33c90 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
33ca0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
33cb0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
33cc0 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
33cd0 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
33ce0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
33cf0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
33d00 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
33d10 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
33d20 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
33d30 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
33d40 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
33d50 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
33d60 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
33d70 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
33d80 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
33d90 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
33da0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
33db0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
33dc0 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
33dd0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
33de0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
33df0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
33e00 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
33e10 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
33e20 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
33e30 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
33e40 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
33e50 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
33e60 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
33e70 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
33e80 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
33e90 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
33ea0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
33eb0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
33ec0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
33ed0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
33ee0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
33ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
33f00 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
33f10 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
33f20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
33f30 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
33f40 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
33f50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
33f60 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
33f70 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
33f80 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
33f90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
33fa0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
33fb0 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
33fc0 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
33fd0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
33fe0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
33ff0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c  te3_stmt.**.** <
34000 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a  b>Summary:</b>.*
34010 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74  * <blockquote><t
34020 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 65  able border=0 ce
34030 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c  llpadding=0 cell
34040 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74  spacing=0>.** <t
34050 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
34060 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e  _column_blob</b>
34070 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c  <td>&rarr;<td>BL
34080 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  OB result.** <tr
34090 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
340a0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62  column_double</b
340b0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52  ><td>&rarr;<td>R
340c0 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  EAL result.** <t
340d0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
340e0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c  _column_int</b><
340f0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d  td>&rarr;<td>32-
34100 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75  bit INTEGER resu
34110 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
34120 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34130 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61  int64</b><td>&ra
34140 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e  rr;<td>64-bit IN
34150 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20  TEGER result.** 
34160 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
34170 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f  e3_column_text</
34180 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
34190 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c  UTF-8 TEXT resul
341a0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
341b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
341c0 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61  ext16</b><td>&ra
341d0 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20 54 45  rr;<td>UTF-16 TE
341e0 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  XT result.** <tr
341f0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34200 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e  column_value</b>
34210 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68  <td>&rarr;<td>Th
34220 65 20 72 65 73 75 6c 74 20 61 73 20 61 6e 20 0a  e result as an .
34230 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
34240 65 7c 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  e|unprotected sq
34250 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34260 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ect..** <tr><td>
34270 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b  &nbsp;<td>&nbsp;
34280 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74  <td>&nbsp;.** <t
34290 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
342a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62  _column_bytes</b
342b0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53  ><td>&rarr;<td>S
342c0 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a  ize of a BLOB.**
342d0 20 6f 72 20 61 20 55 54 46 2d 38 20 54 45 58 54   or a UTF-8 TEXT
342e0 20 72 65 73 75 6c 74 20 69 6e 20 62 79 74 65 73   result in bytes
342f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34300 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34310 74 65 73 31 36 26 6e 62 73 70 3b 26 6e 62 73 70  tes16&nbsp;&nbsp
34320 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61  ;</b>.** <td>&ra
34330 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c  rr;&nbsp;&nbsp;<
34340 74 64 3e 53 69 7a 65 20 6f 66 20 55 54 46 2d 31  td>Size of UTF-1
34350 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62 79 74  6.** TEXT in byt
34360 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  es.** <tr><td><b
34370 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34380 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  type</b><td>&rar
34390 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a  r;<td>Default.**
343a0 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
343b0 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62   result.** </tab
343c0 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  le></blockquote>
343d0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c  .**.** <b>Detail
343e0 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68  s:</b>.**.** ^Th
343f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
34400 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
34410 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
34420 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
34430 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
34440 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
34450 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
34460 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
34470 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
34480 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
34490 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
344a0 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
344b0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
344c0 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
344d0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
344e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
344f0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
34500 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
34510 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
34520 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
34530 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
34540 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
34550 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
34560 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
34570 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
34580 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
34590 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
345a0 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
345b0 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
345c0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
345d0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
345e0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
345f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
34600 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
34610 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
34620 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
34630 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
34640 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
34650 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
34660 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
34670 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
34680 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
34690 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
346a0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
346b0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
346c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
346d0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
346e0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
346f0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
34700 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
34710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
34720 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
34730 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
34740 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
34750 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
34760 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
34770 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
34780 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
34790 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
347a0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
347b0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
347c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
347d0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
347e0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
347f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
34800 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
34810 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
34820 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
34830 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
34840 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
34850 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34860 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
34870 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
34880 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
34890 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
348a0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
348b0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
348c0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
348d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ned..**.** The f
348e0 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61  irst six interfa
348f0 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75  ces (_blob, _dou
34900 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36  ble, _int, _int6
34910 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74  4, _text, and _t
34920 65 78 74 31 36 29 0a 2a 2a 20 65 61 63 68 20 72  ext16).** each r
34930 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75 65 20  eturn the value 
34940 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
34950 6d 6e 20 69 6e 20 61 20 73 70 65 63 69 66 69 63  mn in a specific
34960 20 64 61 74 61 20 66 6f 72 6d 61 74 2e 20 20 49   data format.  I
34970 66 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 20  f.** the result 
34980 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e  column is not in
34990 69 74 69 61 6c 6c 79 20 69 6e 20 74 68 65 20 72  itially in the r
349a0 65 71 75 65 73 74 65 64 20 66 6f 72 6d 61 74 20  equested format 
349b0 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
349c0 20 69 66 20 74 68 65 20 71 75 65 72 79 20 72 65   if the query re
349d0 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
349e0 20 62 75 74 20 74 68 65 20 73 71 6c 69 74 65 33   but the sqlite3
349f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
34a00 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 75  nterface.** is u
34a10 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74  sed to extract t
34a20 68 65 20 76 61 6c 75 65 29 20 74 68 65 6e 20 61  he value) then a
34a30 6e 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65  n automatic type
34a40 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
34a50 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20  erformed..**.** 
34a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
34a70 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
34a80 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
34a90 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
34aa0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
34ab0 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
34ac0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
34ad0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
34ae0 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
34af0 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
34b00 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
34b10 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
34b20 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
34b30 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
34b40 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
34b50 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65  TE_NULL]..** The
34b60 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
34b70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34b80 74 79 70 65 28 29 20 63 61 6e 20 62 65 20 75 73  type() can be us
34b90 65 64 20 74 6f 20 64 65 63 69 64 65 20 77 68 69  ed to decide whi
34ba0 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66 69 72  ch.** of the fir
34bb0 73 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65  st six interface
34bc0 20 73 68 6f 75 6c 64 20 62 65 20 75 73 65 64 20   should be used 
34bd0 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 63  to extract the c
34be0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20  olumn value..** 
34bf0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
34c00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
34c10 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
34c20 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
34c30 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  f no.** automati
34c40 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  c type conversio
34c50 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
34c60 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 20 69   for the value i
34c70 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a  n question.  .**
34c80 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
34c90 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65 20 72 65  nversion, the re
34ca0 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20  sult of calling 
34cb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34cc0 79 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65  ype().** is unde
34cd0 66 69 6e 65 64 2c 20 74 68 6f 75 67 68 20 68 61  fined, though ha
34ce0 72 6d 6c 65 73 73 2e 20 20 46 75 74 75 72 65 0a  rmless.  Future.
34cf0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
34d00 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
34d10 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
34d20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34d30 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
34d40 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
34d50 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
34d60 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
34d70 42 4c 4f 42 20 6f 72 20 61 20 54 45 58 54 20 73  BLOB or a TEXT s
34d80 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  tring, then the 
34d90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34da0 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  ytes().** or sql
34db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34dc0 73 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 73  s16() interfaces
34dd0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
34de0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69  determine the si
34df0 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c  ze.** of that BL
34e00 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
34e10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
34e20 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
34e30 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
34e40 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
34e50 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
34e60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
34e70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
34e80 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
34e90 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
34ea0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
34eb0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
34ec0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
34ed0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
34ee0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
34ef0 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
34f00 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
34f10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34f20 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
34f30 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
34f40 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
34f50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34f60 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
34f70 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
34f80 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
34f90 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
34fa0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
34fb0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
34fc0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
34fd0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
34fe0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
34ff0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
35000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35010 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
35020 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
35030 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
35040 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
35050 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
35060 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35070 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
35080 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
35090 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
350a0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
350b0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
350c0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
350d0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
350e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
350f0 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
35100 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
35110 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
35120 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
35130 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
35140 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
35150 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
35160 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
35170 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
35180 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
35190 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
351a0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
351b0 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
351c0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
351d0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
351e0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
351f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
35200 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
35210 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
35220 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
35230 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
35240 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
35250 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
35260 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35270 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
35280 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35290 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
352a0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
352b0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
352c0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
352d0 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
352e0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
352f0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
35300 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
35310 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
35320 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
35330 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
35340 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
35350 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
35360 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
35370 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
35380 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
35390 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
353a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
353b0 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
353c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
353d0 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
353e0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
353f0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
35400 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
35410 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
35420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35430 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
35440 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
35450 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
35460 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67  **.** <b>Warning
35470 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63  :</b> ^The objec
35480 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
35490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
354a0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
354b0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
354c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
354d0 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74  ct.  In a multit
354e0 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d  hreaded environm
354f0 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f  ent,.** an unpro
35500 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
35510 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
35520 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66  only be used saf
35530 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  ely with.** [sql
35540 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
35550 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
35560 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
35570 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
35580 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35590 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
355a0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
355b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
355c0 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
355d0 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
355e0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
355f0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
35600 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
35610 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
35620 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
35630 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
35640 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
35650 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
35660 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
35670 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68 65 20  ..** Hence, the 
35680 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
35690 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
356a0 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20  .** is normally 
356b0 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77 69 74 68  only useful with
356c0 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  in the implement
356d0 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70  ation of .** [ap
356e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
356f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
35700 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
35710 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e  les], not within
35720 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70  .** top-level ap
35730 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a  plication code..
35740 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73 65 20  **.** The these 
35750 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 61 74 74  routines may att
35760 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
35770 74 68 65 20 64 61 74 61 74 79 70 65 20 6f 66 20  the datatype of 
35780 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  the result..** ^
35790 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
357a0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
357b0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
357c0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
357d0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
357e0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
357f0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
35800 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
35810 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
35820 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
35830 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
35840 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
35850 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
35860 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
35870 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
35880 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
35890 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
358a0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
358b0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
358c0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
358d0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
358e0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
358f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
35900 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
35910 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
35920 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
35930 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
35940 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
35950 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
35960 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
35970 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
35980 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
35990 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
359a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
359b0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
359c0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
359d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
359e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
359f0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
35a00 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
35a10 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
35a20 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
35a30 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
35a40 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
35a50 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
35a60 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
35a70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
35a80 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
35a90 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
35aa0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
35ab0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
35ac0 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
35ad0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35ae0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
35af0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
35b00 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
35b10 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
35b20 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
35b30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
35b40 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
35b50 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
35b60 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
35b70 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
35b80 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
35b90 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
35ba0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
35bb0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
35bc0 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
35bd0 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
35be0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
35bf0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
35c00 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
35c10 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
35c20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
35c30 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
35c40 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
35c50 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
35c60 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
35c70 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
35c80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
35c90 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
35ca0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
35cb0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
35cc0 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
35cd0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
35ce0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e  quote>)^.**.** N
35cf0 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
35d00 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
35d10 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
35d20 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
35d30 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
35d40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
35d50 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
35d60 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
35d70 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
35d80 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
35d90 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
35da0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
35db0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
35dc0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
35dd0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
35de0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
35df0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
35e00 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
35e10 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
35e20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
35e30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35e40 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
35e50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35e60 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
35e70 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
35e80 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
35e90 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
35ea0 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
35eb0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
35ec0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
35ed0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
35ee0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
35ef0 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
35f00 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
35f10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
35f20 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
35f30 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
35f40 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
35f50 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
35f60 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
35f70 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
35f80 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
35f90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35fa0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
35fb0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
35fc0 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
35fd0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
35fe0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
35ff0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
36000 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
36010 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
36020 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
36030 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
36040 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
36050 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
36060 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
36070 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
36080 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
36090 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
360a0 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
360b0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
360c0 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
360d0 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
360e0 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
360f0 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
36100 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
36110 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
36120 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
36130 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
36140 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
36150 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
36160 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
36170 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
36180 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
36190 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70  .** The safest p
361a0 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
361b0 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
361c0 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
361d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
361e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
361f0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
36200 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
36210 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
36220 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
36230 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
36240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
36250 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
36260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36270 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
36280 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
36290 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
362a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
362b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
362c0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
362d0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
362e0 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
362f0 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
36300 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
36310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36320 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
36330 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
36340 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
36350 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
36360 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
36370 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
36380 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36390 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
363a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
363b0 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
363c0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
363d0 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
363e0 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
363f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36400 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
36410 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
36420 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
36430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36440 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
36450 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
36460 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36470 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
36480 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
36490 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
364a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
364b0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
364c0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
364d0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
364e0 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
364f0 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
36500 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
36510 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
36520 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
36530 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
36540 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
36550 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
36560 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
36570 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
36580 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
36590 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
365a0 20 20 44 6f 20 6e 6f 74 20 70 61 73 73 20 74 68    Do not pass th
365b0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
365c0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
365d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
365e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
365f0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
36600 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
36610 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
36620 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
36630 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
36640 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
36650 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
36660 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
36670 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
36680 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
36690 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
366a0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
366b0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
366c0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
366d0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
366e0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
366f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
36700 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
36710 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
36720 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
36730 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
36740 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
36750 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
36760 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
36770 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36780 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
36790 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
367a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
367b0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
367c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
367d0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
367e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
367f0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
36800 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
36810 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36820 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
36830 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
36840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36850 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
36860 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
36870 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
36880 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
36890 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
368a0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
368b0 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
368c0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
368d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
368e0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
368f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
36900 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36910 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
36920 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36930 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
36940 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
36950 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
36960 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
36970 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36990 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
369a0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
369b0 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54  ject.** DESTRUCT
369c0 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
369d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
369e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
369f0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
36a00 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
36a10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36a20 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
36a30 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
36a40 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
36a50 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
36a60 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
36a70 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
36a80 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
36a90 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
36aa0 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
36ab0 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
36ac0 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
36ad0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
36ae0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
36af0 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
36b00 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
36b10 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
36b20 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
36b30 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
36b40 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
36b50 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
36b60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36b70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
36b80 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
36b90 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
36ba0 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
36bb0 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
36bc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36bd0 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
36be0 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
36bf0 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
36c00 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
36c10 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
36c20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
36c30 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
36c40 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
36c50 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
36c60 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
36c70 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
36c80 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
36c90 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
36ca0 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
36cb0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
36cc0 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
36cd0 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
36ce0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
36cf0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
36d00 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
36d10 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
36d20 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
36d30 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
36d40 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
36d50 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
36d60 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
36d70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
36d80 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
36d90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
36da0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
36db0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
36dc0 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
36dd0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
36de0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
36df0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
36e00 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
36e10 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
36e20 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
36e30 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
36e40 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
36e50 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
36e60 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
36e70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
36e80 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
36e90 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
36ea0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
36eb0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48  t Object.** METH
36ec0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
36ed0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
36ee0 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
36ef0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
36f00 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
36f10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
36f20 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
36f30 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
36f40 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
36f50 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
36f60 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
36f70 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
36f80 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
36f90 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
36fa0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
36fb0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
36fc0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
36fd0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
36fe0 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
36ff0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
37000 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
37010 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
37020 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
37030 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
37040 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
37050 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
37060 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
37070 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
37080 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
37090 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
370a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
370b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
370c0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
370d0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
370e0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
370f0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
37100 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
37110 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
37120 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
37130 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
37140 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
37150 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
37160 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
37170 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
37180 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
37190 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
371a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
371b0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
371c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
371d0 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
371e0 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
371f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
37200 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
37210 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
37220 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
37230 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
37240 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
37250 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
37260 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
37270 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
37280 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
37290 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
372a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
372b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
372c0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
372d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
372e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
372f0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
37300 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
37310 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
37320 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
37330 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
37340 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
37350 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
37360 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
37370 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
37380 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
37390 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
373a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
373b0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
373c0 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
373d0 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
373e0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
373f0 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
37400 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
37410 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
37420 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
37430 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
37440 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
37450 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
37460 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
37470 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
37480 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
37490 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
374a0 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
374b0 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
374c0 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
374d0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
374e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
374f0 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
37500 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
37510 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
37520 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
37530 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
37540 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
37550 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
37560 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
37570 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
37580 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37590 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
375a0 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
375b0 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
375c0 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
375d0 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
375e0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
375f0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
37600 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
37610 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
37620 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
37630 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
37640 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
37650 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
37660 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
37670 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
37680 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
37690 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
376a0 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
376b0 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
376c0 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
376d0 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
376e0 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
376f0 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
37700 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
37710 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
37720 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
37730 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
37740 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
37750 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
37760 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
37770 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
37780 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
37790 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
377a0 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
377b0 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
377c0 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
377d0 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
377e0 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
377f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
37800 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
37810 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
37820 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
37830 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
37840 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
37850 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
37860 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
37870 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
37880 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
37890 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
378a0 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
378b0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
378c0 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
378d0 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
378e0 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
378f0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
37900 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
37910 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
37920 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
37930 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
37940 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
37950 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
37960 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
37970 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
37980 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
37990 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
379a0 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
379b0 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
379c0 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
379d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
379e0 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
379f0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68   parameters.  Th
37a00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
37a10 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61  ould set this pa
37a20 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53  rameter to.** [S
37a30 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69  QLITE_UTF16LE] i
37a40 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
37a50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
37a60 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  vokes .** [sqlit
37a70 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
37a80 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
37a90 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
37aa0 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20  16BE] if the.** 
37ab0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
37ac0 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
37ad0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
37ae0 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
37af0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
37b00 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  16] if [sqlite3_
37b10 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
37b20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c  is used, or [SQL
37b30 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68  ITE_UTF8].** oth
37b40 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61  erwise.  ^The sa
37b50 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
37b60 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
37b70 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
37b80 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72   using.** differ
37b90 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65  ent preferred te
37ba0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69  xt encodings, wi
37bb0 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70  th different imp
37bc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
37bd0 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e  .** each encodin
37be0 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  g..** ^When mult
37bf0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
37c00 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
37c10 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
37c20 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
37c30 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
37c40 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
37c50 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
37c60 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
37c70 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ersion..**.** ^T
37c80 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
37c90 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ter may optional
37ca0 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20  ly be ORed with 
37cb0 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
37cc0 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67  ISTIC].** to sig
37cd0 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e  nal that the fun
37ce0 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79  ction will alway
37cf0 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
37d00 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a  e result given.*
37d10 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  * the same input
37d20 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  s within a singl
37d30 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
37d40 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74    Most SQL funct
37d50 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65  ions are.** dete
37d60 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
37d70 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d  built-in [random
37d80 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
37d90 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
37da0 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  f a.** function 
37db0 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65  that is not dete
37dc0 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
37dd0 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61  SQLite query pla
37de0 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a  nner is able to.
37df0 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74  ** perform addit
37e00 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69  ional optimizati
37e10 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69  ons on determini
37e20 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20  stic functions, 
37e30 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65  so use.** of the
37e40 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
37e50 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20  NISTIC] flag is 
37e60 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72  recommended wher
37e70 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a  e possible..**.*
37e80 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
37e90 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
37ea0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
37eb0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
37ec0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
37ed0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
37ee0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
37ef0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
37f00 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
37f10 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
37f20 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
37f30 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
37f40 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
37f50 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
37f60 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
37f70 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
37f80 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
37f90 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
37fa0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
37fb0 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
37fc0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
37fd0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
37fe0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
37ff0 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
38000 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
38010 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
38020 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
38030 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
38040 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
38050 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
38060 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
38070 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
38080 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
38090 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
380a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
380b0 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
380c0 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
380d0 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
380e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
380f0 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
38100 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
38110 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
38120 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
38130 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
38140 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
38150 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
38160 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
38170 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
38180 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
38190 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
381a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
381b0 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
381c0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
381d0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
381e0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
381f0 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
38200 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
38210 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
38220 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
38230 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
38240 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
38250 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
38260 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
38270 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
38280 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
38290 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
382a0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
382b0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
382c0 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
382d0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
382e0 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
382f0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
38300 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
38310 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
38320 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
38330 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
38340 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
38350 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
38360 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
38370 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
38380 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
38390 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
383a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
383b0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
383c0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
383d0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
383e0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
383f0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
38400 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
38410 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
38420 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
38430 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
38440 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
38450 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
38460 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
38470 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
38480 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
38490 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
384a0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
384b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
384c0 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
384d0 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
384e0 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
384f0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
38500 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
38510 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
38520 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
38530 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
38540 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
38550 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
38560 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
38570 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
38580 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
38590 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
385a0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
385b0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
385c0 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
385d0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
385e0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
385f0 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
38600 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
38610 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
38620 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
38630 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
38640 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
38650 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
38660 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
38670 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
38680 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
38690 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
386a0 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
386b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
386c0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
386d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
386e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
386f0 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
38700 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
38710 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
38720 77 65 76 65 72 2c 20 7