/ Hex Artifact Content
Login

Artifact 49b42d0376e7ed94fe71a7338ea19b20185897abaf6b87fd79ec7126c9541c24:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5190: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
51c0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
51d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5280: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
53e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53f0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5410: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5430: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5450: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5470: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5480: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5490: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
54a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54b0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
54c0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
54d0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
54e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54f0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5500: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5510: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5530: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5540: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5550: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5570: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5590: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55b0: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55d0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
55e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55f0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
5600: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5610: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5630: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5650: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5670: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5690: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
56a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56b0: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
56c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56d0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56f0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
5700: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5710: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
5720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5730: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5740: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5750: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5770: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5780: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5790: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
57a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57b0: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
57c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
57d0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57f0: 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20  RR_VNODE        
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5810: 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64  RR | (27<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5830: 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20 20  RR_AUTH         
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5850: 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64  RR | (28<<8)).#d
5860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5870: 52 52 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20  RR_BEGIN_ATOMIC 
5880: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5890: 52 52 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64  RR | (29<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58b0: 52 52 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  RR_COMMIT_ATOMIC
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
58d0: 52 52 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64  RR | (30<<8)).#d
58e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58f0: 52 52 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  RR_ROLLBACK_ATOM
5900: 49 43 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45  IC   (SQLITE_IOE
5910: 52 52 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64  RR | (31<<8)).#d
5920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5930: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
5940: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
5950: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5970: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5980: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5990: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
59a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
59b0: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
59c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
59d0: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
59e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5a00: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5a10: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5a20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a30: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5a40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5a50: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5a80: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5a90: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5aa0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ab0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5ac0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5ad0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5ae0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5b00: 5f 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20  _DIRTYWAL       
5b10: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5b20: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5b30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
5b40: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  T_VTAB          
5b50: 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50    (SQLITE_CORRUP
5b60: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5b80: 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  NLY_RECOVERY    
5b90: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ba0: 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  NLY | (1<<8)).#d
5bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5bc0: 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49 54 20 20  DONLY_CANTINIT  
5bd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5be0: 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a  DONLY | (2<<8)).
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5c00: 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b  EADONLY_ROLLBACK
5c10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5c20: 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29  EADONLY | (3<<8)
5c30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c40: 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45  _READONLY_DBMOVE
5c50: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5c60: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c  _READONLY | (4<<
5c70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c80: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43  TE_ABORT_ROLLBAC
5c90: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  K          (SQLI
5ca0: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38  TE_ABORT | (2<<8
5cb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5cc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45  E_CONSTRAINT_CHE
5cd0: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
5ce0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5cf0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d00: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5d10: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53  _COMMITHOOK   (S
5d20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5d30: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5d40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5d50: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20  AINT_FOREIGNKEY 
5d60: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5d70: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23  AINT | (3<<8)).#
5d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5d90: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f  NSTRAINT_FUNCTIO
5da0: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  N     (SQLITE_CO
5db0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38  NSTRAINT | (4<<8
5dc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5dd0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54  E_CONSTRAINT_NOT
5de0: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54  NULL      (SQLIT
5df0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5e00: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5e10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5e20: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53  _PRIMARYKEY   (S
5e30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5e40: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5e50: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5e60: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20  AINT_TRIGGER    
5e70: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5e80: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23  AINT | (7<<8)).#
5e90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ea0: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20  NSTRAINT_UNIQUE 
5eb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ec0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38  NSTRAINT | (8<<8
5ed0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5ee0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41  E_CONSTRAINT_VTA
5ef0: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  B         (SQLIT
5f00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5f10: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5f20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f30: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53  _ROWID        (S
5f40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f50: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69   |(10<<8)).#defi
5f60: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
5f70: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
5f80: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
5f90: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5fa0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
5fb0: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
5fc0: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
5fd0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5fe0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
5ff0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
6000: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
6010: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  G | (1<<8)).#def
6020: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f  ine SQLITE_AUTH_
6030: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20  USER            
6040: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20     (SQLITE_AUTH 
6050: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
6060: 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44  e SQLITE_OK_LOAD
6070: 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20  _PERMANENTLY    
6080: 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31   (SQLITE_OK | (1
6090: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
60a0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
60b0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
60c0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
60d0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
60e0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
60f0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
6100: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
6110: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
6120: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
6130: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
6140: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
6150: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6160: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
6170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6180: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
6190: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
61a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
61b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
61c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61d0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
61e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
61f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6200: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6220: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
6230: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6240: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6250: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6260: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6270: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
6280: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
6290: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
62a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
62b0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
62c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
62d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
62e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
62f0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
6300: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
6310: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6330: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
6340: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6350: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6360: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6380: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
6390: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
63a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
63b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
63c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63d0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
63e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
63f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6410: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
6420: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6430: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6450: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
6460: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
6470: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6490: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
64a0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
64b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
64c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
64d0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
64e0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
64f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6510: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
6520: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6530: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6550: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6560: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6570: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6590: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
65a0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
65b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
65c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
65d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
65e0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
65f0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
6600: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6610: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6630: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6640: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6650: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6660: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6680: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
6690: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
66a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
66b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
66c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66d0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
66e0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
66f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6700: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
6710: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6720: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
6730: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
6740: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
6750: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
6760: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
6770: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
6780: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
6790: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
67a0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
67b0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
67c0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
67d0: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
67e0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
67f0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
6800: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
6810: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
6820: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
6830: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
6840: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6850: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
6860: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
6870: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6880: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
6890: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
68a0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
68b0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
68c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
68d0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
68e0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
68f0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
6900: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
6910: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
6920: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
6930: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6940: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6950: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6960: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6970: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6980: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
6990: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
69a0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
69b0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
69c0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
69d0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
69e0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
69f0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6a00: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6a10: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6a20: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6a30: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6a40: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6a50: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
6a60: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6a70: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6a80: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
6a90: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
6aa0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6ab0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6ac0: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
6ad0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
6ae0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6af0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6b00: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6b10: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6b20: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6b30: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6b40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
6b50: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
6b60: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
6b70: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
6b80: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
6b90: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
6ba0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
6bb0: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
6bc0: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
6bd0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
6be0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
6bf0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73  * flag indicates
6c00: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e   that a file can
6c10: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77  not be deleted w
6c20: 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a  hen open.  The.*
6c30: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  * SQLITE_IOCAP_I
6c40: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e  MMUTABLE flag in
6c50: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
6c60: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72   file is on.** r
6c70: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61  ead-only media a
6c80: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  nd cannot be cha
6c90: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f  nged even by pro
6ca0: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65  cesses with.** e
6cb0: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67  levated privileg
6cc0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  es..**.** The SQ
6cd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
6ce0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6cf0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
6d00: 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69  underlying.** fi
6d10: 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74  lesystem support
6d20: 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65  s doing multiple
6d30: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
6d40: 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65  s atomically whe
6d50: 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65  n those.** write
6d60: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6d70: 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51  bracketed by [SQ
6d80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
6d90: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61  _ATOMIC_WRITE] a
6da0: 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  nd.** [SQLITE_FC
6db0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
6dc0: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65  C_WRITE]..*/.#de
6dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6de0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6df0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6e00: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6e10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6e20: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6e30: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6e40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6e50: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6e60: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6e70: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6e80: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
6e90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6ea0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
6eb0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6ec0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
6ed0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
6ee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6ef0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6f00: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6f10: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6f20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6f30: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6f40: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6f50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6f60: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6f70: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6f80: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
6f90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6fa0: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
6fb0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
6fc0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6fd0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
6fe0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6ff0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7000: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7010: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
7020: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
7030: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
7040: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
7050: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
7060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7070: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
7080: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
7090: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
70a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
70b0: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
70c0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23      0x00002000.#
70d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
70e0: 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43  CAP_BATCH_ATOMIC
70f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7100: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  04000../*.** CAP
7110: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
7120: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
7130: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
7140: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
7150: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7160: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
7170: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
7180: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
7190: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
71a0: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
71b0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
71c0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
71d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
71e0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
71f0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
7200: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7210: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
7220: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
7230: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
7240: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7250: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
7260: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
7270: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7280: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
7290: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
72a0: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
72b0: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
72c0: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
72d0: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
72e0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
72f0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7300: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
7310: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
7320: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
7330: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
7340: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
7350: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
7360: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7370: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
7380: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
7390: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
73a0: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
73b0: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
73c0: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
73d0: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
73e0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
73f0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
7400: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
7410: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
7420: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7430: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
7440: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
7450: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
7460: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
7470: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
7480: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7490: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
74a0: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
74b0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
74c0: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
74d0: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
74e0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
74f0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7500: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
7510: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
7520: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
7530: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7540: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
7550: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7560: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
7570: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
7580: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
7590: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
75a0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
75b0: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
75c0: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
75d0: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
75e0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
75f0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
7600: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7610: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7620: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
7630: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
7640: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
7650: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
7660: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
7670: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
7680: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
7690: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
76a0: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
76b0: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
76c0: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
76d0: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
76e0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
76f0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
7700: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
7710: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7720: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
7730: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
7740: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
7750: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
7760: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
7770: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
7780: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
7790: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
77a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
77b0: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
77c0: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
77d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
77e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
77f0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
7800: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
7810: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
7820: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7830: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
7840: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
7850: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
7860: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
7870: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
7880: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
7890: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
78a0: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
78b0: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
78c0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
78d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
78e0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
78f0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
7900: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
7910: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
7920: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
7930: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
7940: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
7950: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
7960: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7970: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
7980: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
7990: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
79a0: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
79b0: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
79c0: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
79d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
79e0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
79f0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7a00: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
7a10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7a20: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
7a30: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
7a40: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
7a50: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
7a60: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7a70: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
7a80: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
7a90: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
7aa0: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
7ab0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7ac0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
7ad0: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
7ae0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7af0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
7b00: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
7b10: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
7b20: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7b30: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
7b40: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
7b50: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
7b60: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
7b70: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
7b80: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
7b90: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
7ba0: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
7bb0: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
7bc0: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
7bd0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
7be0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
7bf0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7c00: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7c10: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
7c20: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7c30: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
7c40: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
7c50: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
7c60: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
7c70: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
7c80: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
7c90: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
7ca0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
7cb0: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
7cc0: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
7cd0: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
7ce0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
7cf0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
7d00: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
7d10: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
7d20: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
7d30: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
7d40: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
7d50: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7d60: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
7d70: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
7d80: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7d90: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
7da0: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
7db0: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
7dc0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
7dd0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
7de0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
7df0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
7e00: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
7e10: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
7e20: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
7e30: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
7e40: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
7e50: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
7e60: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
7e70: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
7e80: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
7e90: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
7ea0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
7eb0: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
7ec0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
7ed0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
7ee0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
7ef0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
7f00: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
7f10: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
7f20: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7f30: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
7f40: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
7f50: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
7f60: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
7f70: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
7f80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
7f90: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
7fa0: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
7fb0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
7fc0: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
7fd0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
7fe0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
7ff0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
8000: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
8010: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
8020: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
8030: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
8040: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
8050: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
8060: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
8070: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
8080: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
8090: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
80a0: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
80b0: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
80c0: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
80d0: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
80e0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
80f0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
8100: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
8110: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
8120: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
8130: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
8140: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
8150: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
8160: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
8170: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8180: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
8190: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
81a0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
81b0: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
81c0: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
81d0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
81e0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
81f0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
8200: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
8210: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
8220: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
8230: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
8240: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
8250: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
8260: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
8270: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
8280: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
8290: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
82a0: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
82b0: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
82c0: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
82d0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
82e0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
82f0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
8300: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
8310: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
8320: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
8330: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
8340: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
8350: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
8360: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
8370: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
8380: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
8390: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  [file control op
83a0: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20  codes | list of 
83b0: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
83c0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
83d0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
83e0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
83f0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
8400: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
8410: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
8420: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
8430: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
8440: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
8450: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
8460: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
8470: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
8480: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
8490: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
84a0: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
84b0: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
84c0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
84d0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
84e0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
84f0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
8500: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
8510: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
8520: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
8530: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
8540: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
8550: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
8560: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
8570: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
8580: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
8590: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
85a0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
85b0: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
85c0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
85d0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
85e0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
85f0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
8600: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
8610: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
8620: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8630: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8640: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8650: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8660: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8670: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
8680: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8690: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
86a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
86b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
86c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
86d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
86e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
86f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
8700: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8710: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
8720: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8730: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8740: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8750: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8760: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  UENTIAL].** <li>
8770: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55   [SQLITE_IOCAP_U
8780: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
8790: 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OPEN].** <li> [S
87a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
87b0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
87c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
87d0: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
87e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
87f0: 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54  E_IOCAP_BATCH_AT
8800: 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  OMIC].** </ul>.*
8810: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
8820: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
8830: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8840: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
8850: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
8860: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8870: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8880: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8890: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
88a0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
88b0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
88c0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
88d0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
88e0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
88f0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
8900: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
8910: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8920: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
8930: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
8940: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
8950: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
8960: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
8970: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8980: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8990: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
89a0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
89b0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
89c0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
89d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
89e0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
89f0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8a00: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8a10: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
8a20: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
8a30: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
8a40: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
8a50: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
8a60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
8a70: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8a80: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8a90: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8aa0: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
8ab0: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8ac0: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8ad0: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8ae0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8af0: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8b00: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8b10: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
8b20: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8b30: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
8b40: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
8b50: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
8b60: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
8b70: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8b80: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8b90: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8ba0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8bb0: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8bc0: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8bd0: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8be0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8bf0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8c00: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8c10: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8c20: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8c30: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
8c40: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
8c50: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
8c60: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8c70: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8c80: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8c90: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8ca0: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
8cb0: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8cc0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8cd0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8ce0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8cf0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8d00: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8d10: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
8d20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8d30: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8d40: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
8d50: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8d60: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
8d70: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8d80: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8d90: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8da0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8db0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8dc0: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8dd0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8de0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8df0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8e00: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8e10: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8e20: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8e30: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8e40: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8e50: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8e60: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8e70: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8e80: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8e90: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8ea0: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8eb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ec0: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8ed0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8ee0: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8ef0: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8f00: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8f10: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8f20: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8f30: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
8f40: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8f50: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8f60: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
8f70: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8f80: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8f90: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
8fa0: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
8fb0: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
8fc0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8fd0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8fe0: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
8ff0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
9000: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
9010: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
9020: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
9030: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
9040: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
9050: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
9060: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
9070: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
9080: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
9090: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
90a0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
90b0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
90c0: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
90d0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
90e0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
90f0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
9100: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
9110: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
9120: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
9130: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
9140: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9150: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
9160: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
9170: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9180: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
9190: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
91a0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
91b0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
91c0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
91d0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
91e0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
91f0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
9200: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
9210: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
9220: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
9230: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
9240: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
9250: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
9260: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
9270: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
9280: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
9290: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
92a0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
92b0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
92c0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
92d0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
92e0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
92f0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
9300: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
9310: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
9320: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
9330: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
9340: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
9350: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9360: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
9370: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
9380: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9390: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
93a0: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
93b0: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
93c0: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
93d0: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
93e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
93f0: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
9400: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
9410: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
9420: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
9430: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
9440: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
9450: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
9460: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
9470: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
9480: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
9490: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
94a0: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
94b0: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
94c0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
94d0: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
94e0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
94f0: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
9500: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9510: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9520: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9530: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9540: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
9550: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
9560: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
9570: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9580: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9590: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
95a0: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
95b0: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
95c0: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
95d0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
95e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
95f0: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
9600: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
9610: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
9620: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
9630: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
9640: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
9650: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
9660: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
9670: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9680: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9690: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
96a0: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
96b0: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
96c0: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
96d0: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
96e0: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
96f0: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
9700: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9710: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9720: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9730: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9740: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
9750: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
9760: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
9770: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9780: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9790: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
97a0: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
97b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
97c0: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
97d0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
97e0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
97f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9800: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9810: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9820: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9830: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9840: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9850: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9860: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9870: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9880: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
9890: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
98a0: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
98b0: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
98c0: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
98d0: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
98e0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
98f0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9900: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
9910: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9920: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
9930: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9940: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
9950: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
9960: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
9970: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9980: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9990: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
99a0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
99b0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
99c0: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
99d0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
99e0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
99f0: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9a00: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9a10: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9a20: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9a30: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
9a40: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
9a50: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
9a60: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
9a70: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9a80: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9a90: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9aa0: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9ab0: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9ac0: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9ad0: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9ae0: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9af0: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9b00: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9b10: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9b20: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9b30: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
9b40: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
9b50: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
9b60: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
9b70: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9b80: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9b90: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9ba0: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9bb0: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9bc0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9bd0: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9be0: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9bf0: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9c00: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9c10: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9c20: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9c30: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9c40: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
9c50: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9c60: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9c70: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9c80: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9c90: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9ca0: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9cb0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9cc0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9cd0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9ce0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9cf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9d00: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9d10: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9d20: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9d30: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
9d40: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9d50: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
9d60: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
9d70: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9d80: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9d90: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9da0: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9db0: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9dc0: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9dd0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9de0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9df0: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9e00: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9e10: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9e20: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9e30: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9e40: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9e50: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9e60: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9e70: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9e80: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9e90: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9ea0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9eb0: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9ec0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9ed0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9ee0: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9ef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9f00: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9f10: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9f20: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9f30: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
9f40: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
9f50: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9f60: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9f70: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9f80: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9f90: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9fa0: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9fb0: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9fc0: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9fd0: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9fe0: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9ff0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
a000: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
a010: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
a020: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
a030: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
a040: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
a050: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
a060: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
a070: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
a080: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
a090: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
a0a0: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
a0b0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
a0c0: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
a0d0: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
a0e0: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
a0f0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
a100: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
a110: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
a120: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
a130: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
a140: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
a150: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
a160: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a170: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
a180: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
a190: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
a1a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a1b0: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
a1c0: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
a1d0: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
a1e0: 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 74 72   is the new retr
a1f0: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
a200: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
a210: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
a220: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
a230: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
a240: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
a250: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
a260: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
a270: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
a280: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
a290: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
a2a0: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
a2b0: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
a2c0: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
a2d0: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
a2e0: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
a2f0: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
a300: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
a310: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a320: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a330: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
a340: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
a350: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
a360: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a370: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a380: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
a390: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
a3a0: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
a3b0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
a3c0: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
a3d0: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
a3e0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a3f0: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
a400: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
a410: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
a420: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
a430: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
a440: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
a450: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
a460: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
a470: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a480: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
a490: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
a4a0: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
a4b0: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
a4c0: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
a4d0: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
a4e0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
a4f0: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
a500: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
a510: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
a520: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
a530: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
a540: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
a550: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
a560: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
a570: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
a580: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
a590: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
a5a0: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
a5b0: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
a5c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a5d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a5e0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a5f0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a600: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a610: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a620: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a630: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
a640: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a650: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
a660: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
a670: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a680: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a690: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a6a0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a6b0: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
a6c0: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
a6d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a6e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a6f0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a700: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a710: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a720: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a730: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a740: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a750: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a760: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a770: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a780: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a790: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a7a0: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a7b0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a7c0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a7d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a7e0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a7f0: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a800: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a810: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a820: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a830: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a840: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a850: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a860: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a870: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a880: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a890: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a8a0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a8b0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a8c0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a8d0: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a8e0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a8f0: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a900: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a910: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a920: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a930: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a940: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
a950: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a960: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
a970: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
a980: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
a990: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
a9a0: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
a9b0: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
a9c0: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
a9d0: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
a9e0: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
a9f0: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
aa00: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
aa10: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
aa20: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
aa30: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
aa40: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
aa50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
aa60: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
aa70: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
aa80: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
aa90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
aaa0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
aab0: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
aac0: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
aad0: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
aae0: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
aaf0: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
ab00: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
ab10: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
ab20: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
ab30: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
ab40: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
ab50: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
ab60: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
ab70: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
ab80: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
ab90: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
aba0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
abb0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
abc0: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
abd0: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
abe0: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
abf0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
ac00: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
ac10: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
ac20: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
ac30: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
ac40: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
ac50: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
ac60: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
ac70: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
ac80: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
ac90: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
aca0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
acb0: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
acc0: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
acd0: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
ace0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
acf0: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
ad00: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
ad10: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
ad20: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ad30: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  VFS_POINTER]].**
ad40: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ad50: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
ad60: 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20   opcode finds a 
ad70: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
ad80: 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53  op-level.** [VFS
ad90: 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  es] currently in
ada0: 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67   use.  ^(The arg
adb0: 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71  ument X in.** sq
adc0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
add0: 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e  ol(db,SQLITE_FCN
ade0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58  TL_VFS_POINTER,X
adf0: 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20  ) must be.** of 
ae00: 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76  type "[sqlite3_v
ae10: 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f  fs] **".  This o
ae20: 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20  pcodes will set 
ae30: 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74  *X.** to a point
ae40: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
ae50: 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57  vel VFS.)^.** ^W
ae60: 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75  hen there are mu
ae70: 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73  ltiple VFS shims
ae80: 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74   in the stack, t
ae90: 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  his opcode finds
aea0: 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f   the.** upper-mo
aeb0: 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a  st shim only..**
aec0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
aed0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
aee0: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
aef0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
af00: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
af10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
af20: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
af30: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
af40: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
af50: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
af60: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
af70: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
af80: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
af90: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
afa0: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
afb0: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
afc0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
afd0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
afe0: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
aff0: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
b000: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
b010: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
b020: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
b030: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
b040: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
b050: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
b060: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
b070: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
b080: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
b090: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
b0a0: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
b0b0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
b0c0: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
b0d0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
b0e0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b0f0: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
b100: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
b110: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
b120: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
b130: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
b140: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
b150: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
b160: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
b170: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
b180: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
b190: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
b1a0: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
b1b0: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
b1c0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
b1d0: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
b1e0: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
b1f0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b200: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b210: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
b220: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
b230: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
b240: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
b250: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
b260: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b270: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b280: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
b290: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
b2a0: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
b2b0: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
b2c0: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
b2d0: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
b2e0: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
b2f0: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
b300: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
b310: 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73  statement if res
b320: 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55  ult string is NU
b330: 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75  LL, or that retu
b340: 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66  rns a copy.** of
b350: 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69   the result stri
b360: 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ng if the string
b370: 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a   is non-NULL..**
b380: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b390: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
b3a0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
b3b0: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
b3c0: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
b3d0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
b3e0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
b3f0: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
b400: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
b410: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
b420: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
b430: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
b440: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
b450: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
b460: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
b470: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
b480: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b490: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b4a0: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
b4b0: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
b4c0: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
b4d0: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
b4e0: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
b4f0: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
b500: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
b510: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
b520: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b530: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
b540: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b550: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b560: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
b570: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
b580: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
b590: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
b5a0: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
b5b0: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
b5c0: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
b5d0: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
b5e0: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
b5f0: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
b600: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
b610: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
b620: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b630: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
b640: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
b650: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
b660: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
b670: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
b680: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
b690: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
b6a0: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
b6b0: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
b6c0: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
b6d0: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
b6e0: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
b6f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
b700: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
b710: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
b720: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
b730: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
b740: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
b750: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
b760: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
b770: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
b780: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
b790: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
b7a0: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
b7b0: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
b7c0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
b7d0: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
b7e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b7f0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
b800: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
b810: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
b820: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b830: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
b840: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
b850: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
b860: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
b870: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
b880: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
b890: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
b8a0: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
b8b0: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b8c0: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
b8d0: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
b8e0: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
b8f0: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
b900: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
b910: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
b920: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
b930: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
b940: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
b950: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
b960: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
b970: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
b980: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
b990: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
b9a0: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
b9b0: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
b9c0: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
b9d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b9e0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
b9f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
ba00: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
ba10: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
ba20: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
ba30: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
ba40: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
ba50: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
ba60: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
ba70: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
ba80: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
ba90: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
baa0: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
bab0: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
bac0: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
bad0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
bae0: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
baf0: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
bb00: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
bb10: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
bb20: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
bb30: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
bb40: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
bb50: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
bb60: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
bb70: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
bb80: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
bb90: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
bba0: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
bbb0: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
bbc0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
bbd0: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
bbe0: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
bbf0: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
bc00: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
bc10: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
bc20: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
bc30: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bc40: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
bc50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
bc60: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
bc70: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
bc80: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
bc90: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
bca0: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
bcb0: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
bcc0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
bcd0: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
bce0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
bcf0: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
bd00: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
bd10: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
bd20: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
bd30: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
bd40: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
bd50: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
bd60: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
bd70: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
bd80: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
bd90: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
bda0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
bdb0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
bdc0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
bdd0: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
bde0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bdf0: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
be00: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
be10: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
be20: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
be30: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
be40: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
be50: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
be60: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
be70: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
be80: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
be90: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
bea0: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
beb0: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
bec0: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
bed0: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
bee0: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
bef0: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
bf00: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bf10: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
bf20: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
bf30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
bf40: 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _GET_HANDLE] opc
bf50: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
bf60: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a  to obtain the.**
bf70: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69   underlying nati
bf80: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
bf90: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
bfa0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54   file handle.  T
bfb0: 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74  his file.** cont
bfc0: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
bfd0: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
bfe0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61   pointer to a na
bff0: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
c000: 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74   and.** writes t
c010: 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c  he resulting val
c020: 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ue there..**.** 
c030: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c040: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
c050: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
c060: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c070: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
c080: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
c090: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
c0a0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
c0b0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
c0c0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
c0d0: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
c0e0: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
c0f0: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
c100: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
c110: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
c120: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
c130: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
c140: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
c150: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
c160: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
c170: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
c180: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c190: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a  TL_WAL_BLOCK]].*
c1a0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c1b0: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69  NTL_WAL_BLOCK] i
c1c0: 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68  s a signal to th
c1d0: 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74  e VFS layer that
c1e0: 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20   it might.** be 
c1f0: 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20  advantageous to 
c200: 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78  block on the nex
c210: 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68  t WAL lock if th
c220: 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d  e lock is not im
c230: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61  mediately.** ava
c240: 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c  ilable.  The WAL
c250: 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65   subsystem issue
c260: 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75  s this signal du
c270: 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72  ring rare.** cir
c280: 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72  cumstances in or
c290: 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f  der to fix a pro
c2a0: 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69  blem with priori
c2b0: 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  ty inversion..**
c2c0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
c2d0: 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d  ould <em>not</em
c2e0: 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d  > use this file-
c2f0: 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c  control..**.** <
c300: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c310: 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68  L_ZIPVFS]].** Th
c320: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c330: 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69  ZIPVFS] opcode i
c340: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
c350: 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c   zipvfs only. Al
c360: 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73  l other.** VFS s
c370: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c  hould return SQL
c380: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72  ITE_NOTFOUND for
c390: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a   this opcode..**
c3a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c3b0: 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20  _FCNTL_RBU]].** 
c3c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c3d0: 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73  L_RBU] opcode is
c3e0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
c3f0: 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
c400: 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52  used by.** the R
c410: 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c  BU extension onl
c420: 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46  y.  All other VF
c430: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c440: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c450: 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f  for.** this opco
c460: 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  de.  .**.** <li>
c470: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
c480: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c490: 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53  E]].** If the [S
c4a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c4b0: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
c4c0: 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53  opcode returns S
c4d0: 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a  QLITE_OK, then.*
c4e0: 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72  * the file descr
c4f0: 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20  iptor is placed 
c500: 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 65 20  in "batch write 
c510: 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20  mode", which.** 
c520: 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71  means all subseq
c530: 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61  uent write opera
c540: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65  tions will be de
c550: 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a  ferred and done.
c560: 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74  ** atomically at
c570: 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54   the next [SQLIT
c580: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c590: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53  TOMIC_WRITE].  S
c5a0: 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64  ystems.** that d
c5b0: 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61  o not support ba
c5c0: 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65  tch atomic write
c5d0: 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  s will return SQ
c5e0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a  LITE_NOTFOUND..*
c5f0: 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73  * ^Following a s
c600: 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45  uccessful SQLITE
c610: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c620: 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72  MIC_WRITE and pr
c630: 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c  ior to.** the cl
c640: 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43  osing [SQLITE_FC
c650: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c660: 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b  C_WRITE] or.** [
c670: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
c680: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
c690: 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  TE], SQLite will
c6a0: 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20   make.** no VFS 
c6b0: 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20  interface calls 
c6c0: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c  on the same [sql
c6d0: 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20  ite3_file] file 
c6e0: 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78  descriptor.** ex
c6f0: 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74  cept for calls t
c700: 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d 65 74  o the xWrite met
c710: 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c  hod and the xFil
c720: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
c730: 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ** with [SQLITE_
c740: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
c750: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c760: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c770: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d  T_ATOMIC_WRITE]]
c780: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c790: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c7a0: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64  MIC_WRITE] opcod
c7b0: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69  e causes all wri
c7c0: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73  te.** operations
c7d0: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69   since the previ
c7e0: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63  ous successful c
c7f0: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49  all to .** [SQLI
c800: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c810: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20  TOMIC_WRITE] to 
c820: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f  be performed ato
c830: 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73  mically..** This
c840: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
c850: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
c860: 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
c870: 20 74 68 65 20 77 72 69 74 65 73 20 77 65 72 65   the writes were
c880: 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65  .** all performe
c890: 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  d successfully a
c8a0: 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d  nd have been com
c8b0: 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 69 73  mitted to persis
c8c0: 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a  tent storage..**
c8d0: 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
c8e0: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
c8f0: 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c  t is successful,
c900: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
c910: 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20  ol takes.** the 
c920: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
c930: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69  out of batch wri
c940: 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20  te mode so that 
c950: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
c960: 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  * write operatio
c970: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65  ns are independe
c980: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  nt..** ^SQLite w
c990: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
c9a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
c9b0: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c9c0: 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70  E without.** a p
c9d0: 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
c9e0: 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f  call to [SQLITE_
c9f0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
ca00: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a  IC_WRITE]..**.**
ca10: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ca20: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
ca30: 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54  MIC_WRITE]].** T
ca40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ca50: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
ca60: 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63  _WRITE] opcode c
ca70: 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a  auses all write.
ca80: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69  ** operations si
ca90: 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75 73  nce the previous
caa0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
cab0: 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   to .** [SQLITE_
cac0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
cad0: 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20  IC_WRITE] to be 
cae0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  rolled back..** 
caf0: 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72  ^This file contr
cb00: 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c  ol takes the fil
cb10: 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74  e descriptor out
cb20: 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65 20   of batch write 
cb30: 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20  mode.** so that 
cb40: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77  all subsequent w
cb50: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
cb60: 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e  are independent.
cb70: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
cb80: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51   never invoke SQ
cb90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
cba0: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
cbb0: 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72   without.** a pr
cbc0: 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
cbd0: 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46  all to [SQLITE_F
cbe0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
cbf0: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 20 3c 2f 75  C_WRITE]..** </u
cc00: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
cc10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
cc20: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
cc30: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
cc40: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
cc50: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
cc60: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
cc70: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
cc80: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
cc90: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
cca0: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
ccb0: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
ccc0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
ccd0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
cce0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
ccf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cd00: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
cd10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
cd20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cd30: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
cd40: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
cd50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cd60: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
cd70: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
cd80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cd90: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
cda0: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
cdb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cdc0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
cdd0: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
cde0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cdf0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
ce00: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
ce10: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ce20: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
ce30: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
ce40: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
ce50: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
ce60: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
ce70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
ce80: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
ce90: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
cea0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
ceb0: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
cec0: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
ced0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
cee0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
cef0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
cf00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
cf10: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
cf20: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
cf30: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
cf40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
cf50: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
cf60: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
cf70: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
cf80: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
cf90: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
cfa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
cfb0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
cfc0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
cfd0: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
cfe0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cff0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
d000: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
d010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d020: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20  CNTL_WAL_BLOCK  
d030: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23              24.#
d040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d050: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20  NTL_ZIPVFS      
d060: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64             25.#d
d070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d080: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20  TL_RBU          
d090: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65            26.#de
d0a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d0b0: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20  L_VFS_POINTER   
d0c0: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66           27.#def
d0d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d0e0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
d0f0: 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69          28.#defi
d100: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d110: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
d120: 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e         29.#defin
d130: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
d140: 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20  DB              
d150: 20 20 20 20 20 20 33 30 0a 23 64 65 66 69 6e 65        30.#define
d160: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45   SQLITE_FCNTL_BE
d170: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
d180: 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e 65 20       31.#define 
d190: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
d1a0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
d1b0: 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
d1c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c  QLITE_FCNTL_ROLL
d1d0: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54  BACK_ATOMIC_WRIT
d1e0: 45 20 20 33 33 0a 0a 2f 2a 20 64 65 70 72 65 63  E  33../* deprec
d1f0: 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64  ated names */.#d
d200: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
d210: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
d220: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
d230: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
d240: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
d250: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
d260: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
d270: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
d280: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
d290: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
d2a0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51  O             SQ
d2b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
d2c0: 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ERRNO.../*.** CA
d2d0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
d2e0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
d2f0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
d300: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
d310: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
d320: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
d330: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
d340: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
d350: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
d360: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
d370: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
d380: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
d390: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
d3a0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
d3b0: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
d3c0: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
d3d0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
d3e0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
d3f0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
d400: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
d410: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
d420: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
d430: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
d440: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
d450: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
d460: 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e  adable Extension
d470: 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70   Thunk.**.** A p
d480: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70  ointer to the op
d490: 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69  aque sqlite3_api
d4a0: 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74  _routines struct
d4b0: 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ure is passed as
d4c0: 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61  .** the third pa
d4d0: 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79  rameter to entry
d4e0: 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64   points of [load
d4f0: 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d  able extensions]
d500: 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63  .  This.** struc
d510: 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79 70  ture must be typ
d520: 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20  edefed in order 
d530: 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63  to work around c
d540: 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73  ompiler warnings
d550: 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74  .** on some plat
d560: 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  forms..*/.typede
d570: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
d580: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71  _api_routines sq
d590: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
d5a0: 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  es;../*.** CAPI3
d5b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
d5c0: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
d5d0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
d5e0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
d5f0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
d600: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
d610: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
d620: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
d630: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
d640: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
d650: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
d660: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
d670: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
d680: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
d690: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
d6a0: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
d6b0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
d6c0: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
d6d0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
d6e0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
d6f0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
d700: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
d710: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
d720: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
d730: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
d740: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
d750: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
d760: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
d770: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
d780: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
d790: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
d7a0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
d7b0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
d7c0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
d7d0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
d7e0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
d7f0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
d800: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
d810: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
d820: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
d830: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
d840: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
d850: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
d860: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
d870: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
d880: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
d890: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
d8a0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
d8b0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
d8c0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
d8d0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
d8e0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
d8f0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
d900: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
d910: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
d920: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
d930: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
d940: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
d950: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
d960: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
d970: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
d980: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
d990: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
d9a0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
d9b0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
d9c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
d9d0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
d9e0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
d9f0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
da00: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
da10: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
da20: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
da30: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
da40: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
da50: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
da60: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
da70: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
da80: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
da90: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
daa0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
dab0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
dac0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
dad0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
dae0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
daf0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
db00: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
db10: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
db20: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
db30: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
db40: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
db50: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
db60: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
db70: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
db80: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
db90: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
dba0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
dbb0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
dbc0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
dbd0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
dbe0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
dbf0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
dc00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
dc10: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
dc20: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
dc30: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
dc40: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
dc50: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
dc60: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
dc70: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
dc80: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
dc90: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
dca0: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
dcb0: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
dcc0: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
dcd0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
dce0: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
dcf0: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
dd00: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
dd10: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
dd20: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
dd30: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
dd40: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
dd50: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
dd60: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
dd70: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
dd80: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
dd90: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
dda0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
ddb0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
ddc0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
ddd0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
dde0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
ddf0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
de00: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
de10: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
de20: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
de30: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
de40: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
de50: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
de60: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
de70: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
de80: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
de90: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
dea0: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
deb0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
dec0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
ded0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
dee0: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
def0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
df00: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
df10: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
df20: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
df30: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
df40: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
df50: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
df60: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
df70: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
df80: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
df90: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
dfa0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
dfb0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
dfc0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
dfd0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
dfe0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
dff0: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
e000: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
e010: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
e020: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
e030: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
e040: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
e050: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
e060: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
e070: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
e080: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
e090: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
e0a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
e0b0: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
e0c0: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
e0d0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
e0e0: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
e0f0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
e100: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
e110: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
e120: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
e130: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
e140: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
e150: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
e160: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e170: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
e180: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e190: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
e1a0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
e1b0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
e1c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e1d0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
e1e0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
e1f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
e200: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
e210: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e220: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
e230: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e240: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
e250: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e260: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
e270: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
e280: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
e290: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
e2a0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
e2b0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
e2c0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
e2d0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
e2e0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
e2f0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
e300: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
e310: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
e320: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
e330: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
e340: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
e350: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
e360: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
e370: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
e380: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
e390: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
e3a0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
e3b0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
e3c0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
e3d0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
e3e0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
e3f0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
e400: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
e410: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
e420: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
e430: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
e440: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
e450: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
e460: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
e470: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
e480: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
e490: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
e4a0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
e4b0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
e4c0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
e4d0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
e4e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
e4f0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
e500: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
e510: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
e520: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
e530: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
e540: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
e550: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
e560: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
e570: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
e580: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
e590: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
e5a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
e5b0: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
e5c0: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
e5d0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
e5e0: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
e5f0: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
e600: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
e610: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
e620: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
e630: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
e640: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
e650: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
e660: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
e670: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
e680: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
e690: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
e6a0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
e6b0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
e6c0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
e6d0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
e6e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
e6f0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
e700: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
e710: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
e720: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
e730: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
e740: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
e750: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
e760: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
e770: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
e780: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
e790: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
e7a0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
e7b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
e7c0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
e7d0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
e7e0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
e7f0: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
e800: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
e810: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
e820: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
e830: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
e840: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
e850: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
e860: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
e870: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
e880: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
e890: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
e8a0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
e8b0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
e8c0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
e8d0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
e8e0: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
e8f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
e900: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
e910: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
e920: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
e930: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
e940: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
e950: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
e960: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
e970: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
e980: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
e990: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
e9a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
e9b0: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
e9c0: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
e9d0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
e9e0: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
e9f0: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
ea00: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
ea10: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
ea20: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
ea30: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
ea40: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
ea50: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
ea60: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
ea70: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
ea80: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
ea90: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
eaa0: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
eab0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
eac0: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
ead0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
eae0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
eaf0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
eb00: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
eb10: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
eb20: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
eb30: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
eb40: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
eb50: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
eb60: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
eb70: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
eb80: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
eb90: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
eba0: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
ebb0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
ebc0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
ebd0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
ebe0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
ebf0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
ec00: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
ec10: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
ec20: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
ec30: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
ec40: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
ec50: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
ec60: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
ec70: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
ec80: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
ec90: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
eca0: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
ecb0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
ecc0: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
ecd0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
ece0: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
ecf0: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
ed00: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
ed10: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
ed20: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
ed30: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
ed40: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
ed50: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ed60: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
ed70: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
ed80: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
ed90: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
eda0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
edb0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
edc0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
edd0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
ede0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
edf0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
ee00: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
ee10: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
ee20: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
ee30: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
ee40: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
ee50: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
ee60: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
ee70: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
ee80: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
ee90: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
eea0: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
eeb0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
eec0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
eed0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
eee0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
eef0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
ef00: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
ef10: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
ef20: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
ef30: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
ef40: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
ef50: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
ef60: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
ef70: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
ef80: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
ef90: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
efa0: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
efb0: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
efc0: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
efd0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
efe0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
eff0: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
f000: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
f010: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
f020: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
f030: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
f040: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
f050: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
f060: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
f070: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
f080: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
f090: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
f0a0: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
f0b0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
f0c0: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
f0d0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
f0e0: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
f0f0: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
f100: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
f110: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
f120: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
f130: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
f140: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
f150: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
f160: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
f170: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
f180: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
f190: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
f1a0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
f1b0: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
f1c0: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
f1d0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
f1e0: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
f1f0: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
f200: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
f210: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
f220: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
f230: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
f240: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
f250: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
f260: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
f270: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
f280: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
f290: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
f2a0: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
f2b0: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
f2c0: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
f2d0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
f2e0: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
f2f0: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
f300: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
f310: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
f320: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
f330: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
f340: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
f350: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
f360: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
f370: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
f380: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
f390: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
f3a0: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
f3b0: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
f3c0: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
f3d0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
f3e0: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
f3f0: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
f400: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
f410: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
f420: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
f430: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
f440: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
f450: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
f460: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
f470: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
f480: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
f490: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
f4a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
f4b0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
f4c0: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
f4d0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
f4e0: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
f4f0: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
f500: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
f510: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
f520: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
f530: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
f540: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
f550: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
f560: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
f570: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
f580: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
f590: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
f5a0: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
f5b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f5c0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
f5d0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
f5e0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
f5f0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
f600: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
f610: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
f620: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
f630: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
f640: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
f650: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
f660: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
f670: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
f680: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
f690: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
f6a0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
f6b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f6c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f6d0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
f6e0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
f6f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f700: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f710: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
f720: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
f730: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
f740: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
f750: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f760: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
f770: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
f780: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
f790: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
f7a0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
f7b0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
f7c0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
f7d0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
f7e0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
f7f0: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
f800: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
f810: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
f820: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
f830: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
f840: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
f850: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
f860: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
f870: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
f880: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
f890: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
f8a0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
f8b0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
f8c0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
f8d0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
f8e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
f8f0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
f900: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
f910: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
f920: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
f930: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
f940: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
f950: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
f960: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
f970: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
f980: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
f990: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
f9a0: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
f9b0: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
f9c0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
f9d0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
f9e0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
f9f0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
fa00: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
fa10: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
fa20: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
fa30: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
fa40: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
fa50: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
fa60: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
fa70: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
fa80: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
fa90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
faa0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
fab0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
fac0: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
fad0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
fae0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
faf0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
fb00: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
fb10: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
fb20: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
fb30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
fb40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
fb50: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
fb60: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
fb70: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
fb80: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
fb90: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
fba0: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
fbb0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
fbc0: 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  nded in future v
fbd0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
fbe0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
fbf0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
fc00: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
fc10: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
fc20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fc30: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
fc40: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
fc50: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
fc60: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
fc70: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
fc80: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
fc90: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
fca0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
fcb0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
fcc0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
fcd0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
fce0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
fcf0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
fd00: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
fd10: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
fd20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
fd30: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
fd40: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
fd50: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
fd60: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
fd70: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
fd80: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
fd90: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
fda0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
fdb0: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
fdc0: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
fdd0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
fde0: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
fdf0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
fe00: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
fe10: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
fe20: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
fe30: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
fe40: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
fe50: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
fe60: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
fe70: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
fe80: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
fe90: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
fea0: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
feb0: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
fec0: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
fed0: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
fee0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
fef0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ff00: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
ff10: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
ff20: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
ff30: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
ff40: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
ff50: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
ff60: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
ff70: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
ff80: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
ff90: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
ffa0: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
ffb0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
ffc0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
ffd0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
ffe0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
fff0: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
10000 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
10010 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
10020 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
10030 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
10040 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
10050 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
10060 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
10070 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
10080 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
10090 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
100a0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
100b0 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
100c0 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
100d0 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
100e0 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
100f0 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
10100 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
10110 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
10120 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
10130 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
10140 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
10150 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
10160 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
10170 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
10180 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
10190 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
101a0 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
101b0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
101c0 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
101d0 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
101e0 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
101f0 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
10200 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
10210 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
10220 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
10230 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
10240 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
10250 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
10260 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
10270 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
10280 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20  as given on the 
10290 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
102a0 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
102b0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
102c0 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
102d0 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
102e0 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
102f0 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
10300 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
10310 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
10320 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
10330 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
10340 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
10350 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
10360 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
10370 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10380 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
10390 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
103a0 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
103b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
103c0 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
103d0 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
103e0 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
103f0 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
10400 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
10410 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
10420 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
10430 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
10440 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
10450 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
10460 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
10470 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
10480 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
10490 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
104a0 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
104b0 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
104c0 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
104d0 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
104e0 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
104f0 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
10500 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
10510 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
10520 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
10530 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
10540 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
10550 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
10560 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
10570 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
10580 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
10590 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
105a0 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
105b0 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
105c0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
105d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
105e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
105f0 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
10600 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
10610 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
10620 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
10630 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
10640 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
10650 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
10660 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
10670 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
10680 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
10690 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
106a0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
106b0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
106c0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
106d0 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
106e0 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
106f0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
10700 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10710 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
10720 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
10730 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
10740 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
10750 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
10760 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10770 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
10780 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
10790 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
107a0 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
107b0 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
107c0 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
107d0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
107e0 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
107f0 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
10800 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
10810 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
10820 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
10830 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10840 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
10850 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
10860 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
10870 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
10880 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
10890 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
108a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
108b0 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
108c0 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
108d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
108e0 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
108f0 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
10900 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
10910 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
10920 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10930 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
10940 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
10950 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10960 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
10970 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
10980 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
10990 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
109a0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
109b0 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
109c0 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
109d0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
109e0 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
109f0 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
10a00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
10a10 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
10a20 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
10a30 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
10a40 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
10a50 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
10a60 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
10a70 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
10a80 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
10a90 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
10aa0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10ab0 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
10ac0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10ad0 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
10ae0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10af0 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
10b00 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10b10 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
10b20 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10b30 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
10b40 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
10b50 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
10b60 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
10b70 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
10b80 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
10b90 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
10ba0 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
10bb0 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
10bc0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
10bd0 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
10be0 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
10bf0 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
10c00 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
10c10 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
10c20 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
10c30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
10c40 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
10c50 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
10c60 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
10c70 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
10c80 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
10c90 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
10ca0 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
10cb0 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
10cc0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
10cd0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
10ce0 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
10cf0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
10d00 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
10d10 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10d20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
10d30 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
10d40 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
10d50 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
10d60 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
10d70 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
10d80 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
10d90 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
10da0 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
10db0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
10dc0 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
10dd0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
10de0 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
10df0 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
10e00 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
10e10 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
10e20 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
10e30 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
10e40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10e50 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
10e60 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10e70 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
10e80 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
10e90 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
10ea0 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
10eb0 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
10ec0 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
10ed0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
10ee0 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
10ef0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
10f00 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
10f10 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
10f20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
10f30 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10f40 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
10f50 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
10f60 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
10f70 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
10f80 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
10f90 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
10fa0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
10fb0 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
10fc0 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
10fd0 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
10fe0 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
10ff0 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
11000 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
11010 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
11020 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
11030 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
11040 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
11050 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
11060 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
11070 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
11080 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
11090 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
110a0 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
110b0 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
110c0 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
110d0 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
110e0 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
110f0 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
11100 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
11110 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
11120 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
11130 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
11140 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
11150 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
11160 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
11170 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
11180 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
11190 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
111a0 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
111b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
111c0 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
111d0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
111e0 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
111f0 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
11200 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
11210 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
11220 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
11230 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
11240 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
11250 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
11260 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
11270 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11280 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
11290 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
112a0 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
112b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
112c0 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
112d0 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
112e0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
112f0 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
11300 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
11310 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
11320 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
11330 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
11340 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
11350 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
11360 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
11370 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
11380 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
11390 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
113a0 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
113b0 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
113c0 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
113d0 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
113e0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
113f0 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
11400 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
11410 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
11420 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
11430 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
11440 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
11450 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11460 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
11470 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
11480 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
11490 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
114a0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
114b0 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
114c0 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
114d0 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
114e0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
114f0 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
11500 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
11510 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
11520 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
11530 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
11540 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
11550 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
11560 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
11570 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
11580 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
11590 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
115a0 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
115b0 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
115c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
115d0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
115e0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
115f0 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
11600 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
11610 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
11620 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
11630 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
11640 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
11650 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
11660 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
11670 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
11680 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
11690 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
116a0 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
116b0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
116c0 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
116d0 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
116e0 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
116f0 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
11700 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
11710 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c  l needs..**.** <
11720 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  b>The sqlite3_co
11730 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
11740 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
11750 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74  fe. The applicat
11760 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
11770 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
11780 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11790 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
117a0 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
117b0 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
117c0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
117d0 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20  ning.</b>.**.** 
117e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
117f0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ig() interface.*
11800 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
11810 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
11820 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
11830 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
11840 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11850 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
11860 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
11870 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
11880 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
11890 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
118a0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
118b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
118c0 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
118d0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
118e0 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
118f0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
11900 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
11910 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
11920 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
11930 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
11940 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
11950 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
11960 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
11970 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
11980 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
11990 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
119a0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
119b0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
119c0 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
119d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
119e0 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
119f0 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
11a00 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
11a10 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
11a20 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
11a30 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
11a40 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
11a50 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
11a60 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
11a70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11a80 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
11a90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11aa0 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
11ab0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
11ac0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
11ad0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
11ae0 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
11af0 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
11b00 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
11b10 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
11b20 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
11b30 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
11b40 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
11b50 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
11b60 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
11b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11b80 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
11b90 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
11ba0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
11bb0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11bc0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
11bd0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
11be0 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
11bf0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
11c00 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
11c10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
11c20 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
11c30 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
11c40 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11c50 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
11c60 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
11c70 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
11c80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11c90 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
11ca0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11cb0 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
11cc0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11cd0 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
11ce0 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
11cf0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
11d00 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
11d10 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
11d20 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
11d30 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
11d40 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
11d50 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
11d60 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
11d70 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
11d80 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
11d90 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
11da0 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
11db0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
11dc0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
11dd0 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
11de0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
11df0 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
11e00 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
11e10 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
11e20 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
11e30 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  cessful..*/.int 
11e40 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11e50 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
11e60 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
11e70 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
11e80 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
11e90 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
11ea0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
11eb0 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
11ec0 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
11ed0 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
11ee0 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
11ef0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11f00 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
11f10 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
11f20 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
11f30 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
11f40 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
11f50 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
11f60 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
11f70 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
11f80 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
11f90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11fa0 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
11fb0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11fc0 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
11fd0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
11fe0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11ff0 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
12000 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
12010 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
12020 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
12030 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
12040 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
12050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12060 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
12070 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
12080 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
12090 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
120a0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
120b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
120c0 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
120d0 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
120e0 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
120f0 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
12100 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
12110 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
12120 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
12130 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
12140 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
12150 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
12160 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
12170 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
12180 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
12190 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
121a0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
121b0 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
121c0 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
121d0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
121e0 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
121f0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
12200 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
12210 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
12220 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
12230 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
12240 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
12250 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
12260 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
12270 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
12280 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
12290 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
122a0 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
122b0 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
122c0 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
122d0 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
122e0 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
122f0 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
12300 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
12310 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
12320 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
12330 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
12340 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
12350 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
12360 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
12370 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
12380 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
12390 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
123a0 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
123b0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
123c0 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
123d0 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
123e0 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
123f0 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
12400 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
12410 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
12420 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
12430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12440 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
12450 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
12460 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
12470 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
12480 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
12490 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
124a0 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
124b0 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
124c0 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
124d0 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
124e0 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
124f0 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
12500 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
12510 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
12520 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
12530 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
12540 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
12550 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
12560 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
12570 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
12580 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
12590 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
125a0 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
125b0 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
125c0 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
125d0 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
125e0 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
125f0 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
12600 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
12610 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
12620 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
12630 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
12640 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
12650 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
12660 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
12670 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
12680 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
12690 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
126a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
126b0 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
126c0 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
126d0 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
126e0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
126f0 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tor.  For exampl
12700 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
12710 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
12720 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
12730 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
12740 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
12750 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
12760 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
12770 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
12780 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
12790 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
127a0 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
127b0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
127c0 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
127d0 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
127e0 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
127f0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
12800 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
12810 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
12820 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
12830 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
12840 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
12850 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
12860 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
12870 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
12880 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
12890 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
128a0 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
128b0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
128c0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
128d0 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
128e0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
128f0 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
12900 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
12910 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
12920 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
12930 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
12940 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
12950 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
12960 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
12970 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
12980 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
12990 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
129a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
129b0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
129c0 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
129d0 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
129e0 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
129f0 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
12a00 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
12a10 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
12a20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12a30 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
12a40 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
12a50 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
12a60 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
12a70 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
12a80 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
12a90 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
12aa0 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
12ab0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
12ac0 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
12ad0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
12ae0 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
12af0 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
12b00 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
12b10 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
12b20 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
12b30 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
12b40 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
12b50 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
12b60 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
12b70 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
12b80 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
12b90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
12ba0 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
12bb0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
12bc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
12bd0 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
12be0 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
12bf0 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
12c00 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
12c10 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
12c20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
12c30 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
12c40 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
12c50 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
12c60 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
12c70 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
12c80 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
12c90 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
12ca0 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
12cb0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
12cc0 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
12cd0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
12ce0 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
12cf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
12d00 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
12d10 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
12d20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
12d30 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
12d40 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
12d50 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
12d60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
12d70 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
12d80 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
12d90 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
12da0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
12db0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
12dc0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
12dd0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12de0 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
12df0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
12e00 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
12e10 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
12e20 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
12e30 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
12e40 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
12e50 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
12e60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12e70 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
12e80 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
12e90 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
12ea0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
12eb0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
12ec0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
12ed0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
12ee0 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
12ef0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
12f00 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
12f10 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
12f20 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
12f30 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
12f40 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
12f50 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
12f60 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
12f70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12f80 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
12f90 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
12fa0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
12fb0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
12fc0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
12fd0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
12fe0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
12ff0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
13000 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
13010 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
13020 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
13030 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
13040 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
13050 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
13060 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
13070 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
13080 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
13090 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
130a0 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
130b0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
130c0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
130d0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
130e0 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
130f0 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
13100 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
13110 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
13120 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
13130 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
13140 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
13150 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
13160 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13170 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
13180 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13190 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
131a0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
131b0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
131c0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
131d0 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
131e0 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
131f0 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
13200 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13210 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
13220 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
13230 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
13240 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
13250 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
13260 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
13270 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
13280 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13290 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
132a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
132b0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
132c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
132d0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
132e0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
132f0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
13300 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
13310 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
13320 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
13330 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
13340 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
13350 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
13360 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13370 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
13380 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
13390 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
133a0 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
133b0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
133c0 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
133d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
133e0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
133f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
13400 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
13410 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
13420 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
13430 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
13440 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
13450 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
13460 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
13470 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
13480 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
13490 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
134a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
134b0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
134c0 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
134d0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
134e0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
134f0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13500 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13510 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13520 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13530 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
13540 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
13550 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
13560 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
13570 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
13580 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
13590 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
135a0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
135b0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
135c0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
135d0 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
135e0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
135f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13600 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
13610 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13620 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
13630 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
13640 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
13650 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
13660 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
13670 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
13680 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
13690 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
136a0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
136b0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
136c0 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
136d0 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
136e0 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
136f0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
13700 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
13710 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13720 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
13730 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
13740 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
13750 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
13760 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13770 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
13780 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
13790 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
137a0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
137b0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
137c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
137d0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
137e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
137f0 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
13800 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
13810 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
13820 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
13830 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
13840 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
13850 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
13860 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
13870 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
13880 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
13890 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
138a0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
138b0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
138c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
138d0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
138e0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
138f0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
13900 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
13910 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
13920 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
13930 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13940 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
13950 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
13960 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13970 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
13980 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
13990 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
139a0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
139b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
139c0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
139d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
139e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
139f0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13a00 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  G_MALLOC option 
13a10 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13a20 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13a30 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
13a40 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
13a50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
13a60 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
13a70 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
13a80 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
13a90 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
13aa0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
13ab0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13ac0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
13ad0 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
13ae0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13af0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
13b00 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
13b10 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
13b20 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
13b30 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
13b40 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
13b50 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13b60 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
13b70 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
13b80 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
13b90 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
13ba0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13bb0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
13bc0 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
13bd0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
13be0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13bf0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13c00 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  _GETMALLOC optio
13c10 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13c20 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
13c30 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
13c40 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
13c50 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13c60 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
13c70 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73  cture..** The [s
13c80 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13c90 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
13ca0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
13cb0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
13cc0 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
13cd0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
13ce0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
13cf0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
13d00 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
13d10 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
13d20 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
13d30 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
13d40 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
13d50 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
13d60 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
13d70 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
13d80 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
13d90 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
13da0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13db0 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d  IG_SMALL_MALLOC]
13dc0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13dd0 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43  FIG_SMALL_MALLOC
13de0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13df0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13e00 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70  _SMALL_MALLOC op
13e10 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
13e20 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a  e argument of.**
13e30 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
13e40 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
13e50 65 61 6e 2c 20 77 68 69 63 68 20 69 66 20 74 72  ean, which if tr
13e60 75 65 20 70 72 6f 76 69 64 65 73 20 61 20 68 69  ue provides a hi
13e70 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20  nt to.** SQLite 
13e80 74 68 61 74 20 69 74 20 73 68 6f 75 6c 64 20 61  that it should a
13e90 76 6f 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72  void large memor
13ea0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66  y allocations if
13eb0 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51   possible..** SQ
13ec0 4c 69 74 65 20 77 69 6c 6c 20 72 75 6e 20 66 61  Lite will run fa
13ed0 73 74 65 72 20 69 66 20 69 74 20 69 73 20 66 72  ster if it is fr
13ee0 65 65 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65  ee to make large
13ef0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13f00 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65  ons,.** but some
13f10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
13f20 68 74 20 70 72 65 66 65 72 20 74 6f 20 72 75 6e  ht prefer to run
13f30 20 73 6c 6f 77 65 72 20 69 6e 20 65 78 63 68 61   slower in excha
13f40 6e 67 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61  nge for.** guara
13f50 6e 74 65 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f  ntees about memo
13f60 72 79 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  ry fragmentation
13f70 20 74 68 61 74 20 61 72 65 20 70 6f 73 73 69 62   that are possib
13f80 6c 65 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61  le if large.** a
13f90 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 61  llocations are a
13fa0 76 6f 69 64 65 64 2e 20 20 54 68 69 73 20 68 69  voided.  This hi
13fb0 6e 74 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f  nt is normally o
13fc0 66 66 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ff..** </dd>.**.
13fd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13fe0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
13ff0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14000 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
14010 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
14020 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14030 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65  ATUS option take
14040 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
14050 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a  t of type int,.*
14060 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  * interpreted as
14070 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63   a boolean, whic
14080 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
14090 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
140a0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72  tion of.** memor
140b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
140c0 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
140d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
140e0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
140f0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68  .** disabled, th
14100 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
14110 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
14120 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
14130 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
14140 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
14150 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
14160 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
14170 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
14180 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
14190 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
141a0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
141b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
141c0 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a  te3_status64()].
141d0 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
141e0 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
141f0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
14200 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
14210 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
14220 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
14230 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
14240 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
14250 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
14260 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
14270 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14280 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
14290 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
142a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
142b0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
142c0 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
142d0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
142e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
142f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14300 41 54 43 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e  ATCH option is n
14310 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a  o longer used..*
14320 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
14330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14340 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
14350 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14360 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
14370 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
14380 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
14390 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
143a0 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a   a memory pool.*
143b0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
143c0 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61  n use for the da
143d0 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
143e0 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
143f0 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  lt page.** cache
14400 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
14410 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
14420 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14430 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e  is a no-op if an
14440 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
14450 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
14460 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14470 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
14480 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
14490 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a  FIG_PCACHE2]..**
144a0 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
144b0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
144c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
144d0 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65  ECACHE: A pointe
144e0 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61  r to.** 8-byte a
144f0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70  ligned memory (p
14500 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f  Mem), the size o
14510 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63 68  f each page cach
14520 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20  e line (sz),.** 
14530 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
14540 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e  f cache lines (N
14550 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
14560 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
14570 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
14580 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
14590 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
145a0 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
145b0 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 20   512 and 65536) 
145c0 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20  plus some extra 
145d0 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a  bytes for each.*
145e0 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
145f0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65  ^The number of e
14600 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 65  xtra bytes neede
14610 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68 65  d by the page he
14620 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64  ader.** can be d
14630 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
14640 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
14650 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a  CACHE_HDRSZ]..**
14660 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
14670 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
14680 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
14690 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61  ** for the sz pa
146a0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61  rameter to be la
146b0 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73  rger than necess
146c0 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a  ary.  The pMem.*
146d0 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
146e0 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
146f0 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f   pointer or a po
14700 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
14710 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c  te.** aligned bl
14720 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66  ock of memory of
14730 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
14740 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a  ytes, otherwise.
14750 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  ** subsequent be
14760 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
14770 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d  ned..** ^When pM
14780 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  em is not NULL, 
14790 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69  SQLite will stri
147a0 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65  ve to use the me
147b0 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a  mory provided.**
147c0 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 65   to satisfy page
147d0 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61   cache needs, fa
147e0 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73  lling back to [s
147f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14800 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61   if.** a page ca
14810 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67  che line is larg
14820 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73  er than sz bytes
14830 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68   or if all of th
14840 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a  e pMem buffer.**
14850 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
14860 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55  * ^If pMem is NU
14870 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d  LL and N is non-
14880 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20  zero, then each 
14890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
148a0 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69  ion.** does an i
148b0 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f  nitial bulk allo
148c0 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20  cation for page 
148d0 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  cache memory.** 
148e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
148f0 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65  lloc()] sufficie
14900 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c  nt for N cache l
14910 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73  ines if N is pos
14920 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d  itive or.** of -
14930 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20  1024*N bytes if 
14940 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e  N is negative, .
14950 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
14960 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
14970 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
14980 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
14990 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69 6e  ovided by the in
149a0 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74  itial.** allocat
149b0 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ion, then SQLite
149c0 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
149d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61  3_malloc()] sepa
149e0 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a  rately for each.
149f0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61  ** additional ca
14a00 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a  che line. </dd>.
14a10 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14a20 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74  ONFIG_HEAP]] <dt
14a30 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
14a40 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
14a50 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14a60 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
14a70 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
14a80 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
14a90 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65   .** that SQLite
14aa0 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c   will use for al
14ab0 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
14ac0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14ad0 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f  on needs.** beyo
14ae0 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
14af0 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  d for by [SQLITE
14b00 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14b10 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
14b20 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
14b30 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
14b40 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
14b50 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
14b60 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
14b70 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
14b80 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
14b90 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
14ba0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
14bb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14bc0 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
14bd0 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
14be0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
14bf0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
14c00 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
14c10 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
14c20 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
14c30 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
14c40 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
14c50 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
14c60 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
14c70 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
14c80 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
14c90 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14ca0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14cb0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
14cc0 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
14cd0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
14ce0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
14cf0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
14d00 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
14d10 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
14d20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
14d30 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
14d40 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14d50 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
14d60 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
14d70 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
14d80 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
14d90 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
14da0 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
14db0 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
14dc0 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
14dd0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14de0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
14df0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14e00 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
14e10 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
14e20 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
14e30 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
14e40 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
14e50 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
14e60 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
14e70 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
14e80 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
14e90 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
14ea0 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
14eb0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
14ec0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
14ed0 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
14ee0 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
14ef0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14f00 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
14f10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14f20 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
14f30 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14f40 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
14f50 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14f60 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14f70 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
14f80 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14f90 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14fa0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14fb0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
14fc0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
14fd0 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
14fe0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
14ff0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
15000 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
15010 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
15020 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
15030 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
15040 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
15050 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
15060 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15070 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
15080 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
15090 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
150a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
150b0 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
150c0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
150d0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
150e0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
150f0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
15100 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
15110 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
15120 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
15130 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
15140 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
15150 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
15160 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
15170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
15180 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
15190 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
151a0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
151b0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
151c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
151d0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
151e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
151f0 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
15200 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
15210 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
15220 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
15230 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15240 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
15250 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
15260 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
15270 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
15280 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
15290 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
152a0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
152b0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
152c0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
152d0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
152e0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
152f0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
15300 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
15310 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
15320 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
15330 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
15340 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
15350 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
15360 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
15370 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
15380 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
15390 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
153a0 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
153b0 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
153c0 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
153d0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
153e0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
153f0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
15400 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
15410 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
15420 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
15430 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
15440 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
15450 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
15460 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
15470 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
15480 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
15490 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
154a0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
154b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
154c0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
154d0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
154e0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
154f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15500 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
15510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
15520 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
15530 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15540 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15550 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
15560 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
15570 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
15580 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
15590 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
155a0 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
155b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
155c0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
155d0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
155e0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
155f0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
15600 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
15610 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
15620 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
15630 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
15640 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15650 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
15660 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
15670 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
15680 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
15690 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
156a0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
156b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
156c0 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
156d0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
156e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
156f0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
15700 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
15710 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
15720 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
15730 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
15740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15750 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
15760 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15770 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
15780 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15790 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
157a0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
157b0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
157c0 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
157d0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
157e0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
157f0 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
15800 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
15810 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
15820 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
15830 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
15840 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
15850 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
15860 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
15870 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15880 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
15890 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
158a0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
158b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
158c0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
158d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
158e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
158f0 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
15900 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15910 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
15920 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15930 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
15940 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
15950 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
15960 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
15970 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
15980 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
15990 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
159a0 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
159b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
159c0 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
159d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
159e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
159f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15a00 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
15a10 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
15a20 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
15a30 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
15a40 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
15a50 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
15a60 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
15a70 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
15a80 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
15a90 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
15aa0 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
15ab0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
15ac0 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
15ad0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
15ae0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
15af0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
15b00 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
15b10 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
15b20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
15b30 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
15b40 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
15b50 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
15b60 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
15b70 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
15b80 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
15b90 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
15ba0 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
15bb0 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
15bc0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15bd0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
15be0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
15bf0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
15c00 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
15c10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
15c20 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
15c30 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
15c40 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
15c50 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
15c60 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
15c70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
15c80 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
15c90 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
15ca0 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
15cb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15cc0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
15cd0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
15ce0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
15cf0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
15d00 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
15d10 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
15d20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
15d30 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
15d40 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
15d50 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
15d60 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
15d70 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
15d80 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
15d90 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
15da0 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
15db0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
15dc0 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
15dd0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
15de0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
15df0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
15e00 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
15e10 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
15e20 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
15e30 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
15e40 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
15e50 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
15e60 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
15e70 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
15e80 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
15e90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15ea0 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
15eb0 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
15ec0 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
15ed0 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
15ee0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15ef0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
15f00 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
15f10 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
15f20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
15f30 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
15f40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
15f50 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
15f60 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
15f70 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
15f80 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
15f90 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
15fa0 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
15fb0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
15fc0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
15fd0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
15fe0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
15ff0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
16000 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
16010 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
16020 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
16030 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
16040 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
16050 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
16060 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
16070 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
16080 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
16090 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
160a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
160b0 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
160c0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
160d0 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
160e0 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
160f0 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
16100 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
16110 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
16120 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
16130 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16140 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
16150 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
16160 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
16170 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
16180 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
16190 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
161a0 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
161b0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
161c0 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
161d0 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
161e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
161f0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
16200 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
16210 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
16220 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
16230 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16240 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
16250 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
16260 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16270 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
16280 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
16290 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
162a0 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
162b0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
162c0 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
162d0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
162e0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
162f0 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
16300 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
16310 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
16320 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
16330 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
16340 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
16350 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
16360 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
16370 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
16380 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
16390 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
163a0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
163b0 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
163c0 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
163d0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
163e0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
163f0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
16400 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
16410 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
16420 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
16430 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
16440 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
16450 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
16460 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
16470 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
16480 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
16490 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
164a0 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
164b0 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
164c0 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
164d0 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
164e0 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
164f0 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
16500 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
16510 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16520 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
16530 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16540 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16550 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
16560 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
16570 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
16580 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
16590 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
165a0 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
165b0 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
165c0 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
165d0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
165e0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
165f0 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
16600 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
16610 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16620 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
16630 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16640 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
16650 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
16660 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
16670 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
16680 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
16690 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
166a0 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
166b0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
166c0 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
166d0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
166e0 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
166f0 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
16700 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
16710 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
16720 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
16730 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
16740 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
16750 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
16760 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16770 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
16780 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
16790 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
167a0 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
167b0 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
167c0 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
167d0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
167e0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
167f0 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
16800 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
16810 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
16820 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
16830 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
16840 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
16850 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
16860 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
16870 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
16880 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
16890 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
168a0 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
168b0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
168c0 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
168d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
168e0 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
168f0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
16900 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
16910 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
16920 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
16930 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
16940 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
16950 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
16960 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
16970 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
16980 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
16990 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
169a0 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
169b0 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
169c0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
169d0 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
169e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
169f0 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
16a00 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
16a10 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
16a20 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
16a30 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
16a40 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
16a50 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16a60 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
16a70 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16a80 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16a90 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
16aa0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16ab0 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
16ac0 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
16ad0 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
16ae0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
16af0 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
16b00 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
16b10 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
16b20 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
16b30 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
16b40 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
16b50 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
16b60 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
16b70 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
16b80 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
16b90 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
16ba0 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
16bb0 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
16bc0 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
16bd0 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
16be0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
16bf0 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
16c00 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
16c10 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
16c20 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
16c30 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
16c40 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
16c50 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
16c60 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
16c70 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
16c80 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
16c90 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
16ca0 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
16cb0 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
16cc0 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
16cd0 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
16ce0 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
16cf0 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
16d00 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
16d10 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
16d20 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
16d30 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
16d40 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
16d50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16d60 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16d70 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16d80 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16d90 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
16da0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16db0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
16dc0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
16dd0 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
16de0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
16df0 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
16e00 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
16e10 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
16e20 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
16e30 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
16e40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16e50 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
16e60 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
16e70 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
16e80 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
16e90 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
16ea0 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
16eb0 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
16ec0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
16ed0 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
16ee0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16ef0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
16f00 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16f10 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16f20 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
16f30 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
16f40 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
16f50 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
16f60 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
16f70 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
16f80 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
16f90 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
16fa0 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
16fb0 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
16fc0 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
16fd0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
16fe0 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
16ff0 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
17000 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
17010 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
17020 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
17030 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
17040 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
17050 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
17060 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17070 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
17080 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
17090 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
170a0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
170b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
170c0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
170d0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
170e0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
170f0 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
17100 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
17110 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
17120 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
17130 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
17140 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
17150 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
17160 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
17170 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
17180 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
17190 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
171a0 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
171b0 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
171c0 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
171d0 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
171e0 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
171f0 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
17200 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
17210 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
17220 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
17230 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
17240 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
17250 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
17260 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
17270 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
17280 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
17290 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
172a0 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  his value..**.**
172b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
172c0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
172d0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
172e0 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
172f0 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68  SPILL.** <dd>^Th
17300 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17310 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f  STMTJRNL_SPILL o
17320 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17330 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
17340 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20  hich.** becomes 
17350 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a  the [statement j
17360 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f  ournal] spill-to
17370 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e  -disk threshold.
17380 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74    .** [Statement
17390 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68   journals] are h
173a0 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e  eld in memory un
173b0 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28  til their size (
173c0 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63  in bytes).** exc
173d0 65 65 64 73 20 74 68 69 73 20 74 68 72 65 73 68  eeds this thresh
173e0 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f  old, at which po
173f0 69 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 69  int they are wri
17400 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a  tten to disk..**
17410 20 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 73   Or if the thres
17420 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74  hold is -1, stat
17430 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61  ement journals a
17440 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a  re always held.*
17450 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e  * exclusively in
17460 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63   memory..** Sinc
17470 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74  e many statement
17480 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20   journals never 
17490 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65  become large, se
174a0 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a  tting the spill.
174b0 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20  ** threshold to 
174c0 61 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 20  a value such as 
174d0 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c  64KiB can greatl
174e0 79 20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f  y reduce the amo
174f0 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65  unt of.** I/O re
17500 71 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72  quired to suppor
17510 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c  t statement roll
17520 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66  back..** The def
17530 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
17540 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 63  his setting is c
17550 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65  ontrolled by the
17560 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54  .** [SQLITE_STMT
17570 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70  JRNL_SPILL] comp
17580 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
17590 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
175a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
175b0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
175c0 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
175d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
175e0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
175f0 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
17600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17610 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
17620 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
17630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17640 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
17650 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
17660 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
17670 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17680 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
17690 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
176a0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
176b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
176c0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
176d0 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 4e 6f  H       6  /* No
176e0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
176f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17700 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
17710 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
17720 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
17730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17740 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
17750 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
17760 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
17770 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
17780 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17790 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
177a0 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
177b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
177c0 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
177d0 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
177e0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
177f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17800 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
17810 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
17820 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
17830 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
17840 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
17850 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
17860 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
17870 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
17880 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
17890 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
178a0 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
178b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
178c0 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
178d0 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
178e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
178f0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
17900 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
17910 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17920 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
17930 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
17940 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
17950 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17960 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
17970 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
17980 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17990 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
179a0 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
179b0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
179c0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
179d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
179e0 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
179f0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
17a00 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
17a10 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17a20 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
17a30 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
17a40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17a50 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20  E_CONFIG_SQLLOG 
17a60 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71        21  /* xSq
17a70 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  llog, void* */.#
17a80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17a90 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  NFIG_MMAP_SIZE  
17aa0 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33    22  /* sqlite3
17ab0 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f  _int64, sqlite3_
17ac0 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65  int64 */.#define
17ad0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
17ae0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20  IN32_HEAPSIZE   
17af0 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42     23  /* int nB
17b00 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  yte */.#define S
17b10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17b20 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20  CHE_HDRSZ       
17b30 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a   24  /* int *psz
17b40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17b50 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
17b60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
17b70 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e    /* unsigned in
17b80 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69  t szPma */.#defi
17b90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17ba0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20  _STMTJRNL_SPILL 
17bb0 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74 20       26  /* int 
17bc0 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
17bd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17be0 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  MALL_MALLOC     
17bf0 20 20 20 32 37 20 20 2f 2a 20 62 6f 6f 6c 65 61     27  /* boolea
17c00 6e 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  n */../*.** CAPI
17c10 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
17c20 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
17c30 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
17c40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
17c50 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
17c60 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
17c70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
17c80 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
17c90 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
17ca0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
17cb0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
17cc0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17cd0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
17ce0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
17cf0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
17d00 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
17d10 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
17d20 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
17d30 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
17d40 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
17d50 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
17d60 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
17d70 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
17d80 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
17d90 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
17da0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
17db0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
17dc0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
17dd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
17de0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17df0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
17e00 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
17e10 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
17e20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
17e30 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
17e40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17e50 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
17e60 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
17e70 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17e80 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
17e90 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
17ea0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
17eb0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
17ec0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
17ed0 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
17ee0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
17ef0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
17f00 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
17f10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17f20 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
17f30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
17f40 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
17f50 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
17f60 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
17f70 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
17f80 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
17f90 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
17fa0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
17fb0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
17fc0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
17fd0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
17fe0 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
17ff0 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
18000 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
18010 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
18020 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
18030 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
18040 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
18050 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
18060 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
18070 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
18080 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
18090 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
180a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
180b0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
180c0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
180d0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
180e0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
180f0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
18100 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
18110 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
18120 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
18130 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
18140 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
18150 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
18160 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
18170 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
18180 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
18190 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
181a0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
181b0 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
181c0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
181d0 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
181e0 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
181f0 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
18200 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
18210 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
18220 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
18230 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
18240 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
18250 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
18260 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
18270 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
18280 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
18290 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
182a0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
182b0 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
182c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
182d0 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
182e0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
182f0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
18300 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
18310 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
18320 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
18330 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
18340 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
18350 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
18360 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
18370 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
18380 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
18390 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
183a0 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
183b0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
183c0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
183d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
183e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
183f0 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
18400 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
18410 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
18420 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
18430 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
18440 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
18450 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
18460 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
18470 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
18480 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
18490 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
184a0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
184b0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
184c0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
184d0 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
184e0 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
184f0 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
18500 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
18510 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
18520 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
18530 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18540 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
18550 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
18560 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
18570 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
18580 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
18590 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
185a0 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
185b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
185c0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
185d0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
185e0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
185f0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
18600 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
18610 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
18620 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
18630 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
18640 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18650 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
18660 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
18670 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18680 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
18690 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
186a0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
186b0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
186c0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
186d0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
186e0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
186f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
18700 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
18710 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
18720 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
18730 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
18740 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
18750 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
18760 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
18770 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
18780 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18790 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
187a0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
187b0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
187c0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
187d0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
187e0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
187f0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
18800 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
18810 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18820 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
18830 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
18840 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
18850 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
18860 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
18870 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
18880 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18890 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
188a0 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
188b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
188c0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
188d0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
188e0 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d  disable the two-
188f0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73  argument.** vers
18900 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33  ion of the [fts3
18910 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75  _tokenizer()] fu
18920 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20  nction which is 
18930 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  part of the.** [
18940 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20  FTS3] full-text 
18950 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78  search engine ex
18960 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72  tension..** Ther
18970 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
18980 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
18990 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
189a0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
189b0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
189c0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
189d0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
189e0 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20   or.** positive 
189f0 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74  to enable fts3_t
18a00 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65  okenizer() or ne
18a10 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
18a20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  the setting.** u
18a30 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
18a40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18a50 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
18a60 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
18a70 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
18a80 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
18a90 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
18aa0 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20   fts3_tokenizer 
18ab0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
18ac0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
18ad0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
18ae0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18af0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
18b00 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
18b10 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
18b20 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
18b30 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
18b40 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
18b50 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18b60 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
18b70 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a  XTENSION</dt>.**
18b80 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18b90 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
18ba0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
18bb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
18bc0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
18bd0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65  * interface inde
18be0 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65  pendently of the
18bf0 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
18c00 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
18c10 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
18c20 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
18c30 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65  tension()] API e
18c40 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
18c50 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43  es both the.** C
18c60 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  -API [sqlite3_lo
18c70 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
18c80 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18c90 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e  tion [load_exten
18ca0 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72  sion()]..** Ther
18cb0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
18cc0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
18cd0 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  ents..** When th
18ce0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18cf0 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61   to this interfa
18d00 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e  ce is 1, then on
18d10 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a  ly the C-API is.
18d20 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74  ** enabled and t
18d30 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
18d40 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64  remains disabled
18d50 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
18d60 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
18d70 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
18d80 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68   0, then both th
18d90 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20  e C-API and the 
18da0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  SQL function are
18db0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66   disabled..** If
18dc0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
18dd0 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ent is -1, then 
18de0 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d  no changes are m
18df0 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20  ade to state of 
18e00 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d  either the.** C-
18e10 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66  API or the SQL f
18e20 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
18e30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18e40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18e50 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
18e60 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
18e70 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
18e80 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
18e90 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
18ea0 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72  tension()] inter
18eb0 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62  face.** is disab
18ec0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66  led or enabled f
18ed0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18ee0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18ef0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a  parameter may.**
18f00 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
18f10 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  er, in which cas
18f20 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
18f30 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
18f40 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e  d back..** </dd>
18f50 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18f60 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
18f70 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BNAME</dt>.** <d
18f80 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18f90 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  is used to chang
18fa0 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
18fb0 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73  e "main" databas
18fc0 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54  e.** schema.  ^T
18fd0 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74  he sole argument
18fe0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18ff0 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38   a constant UTF8
19000 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68   string.** which
19010 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
19020 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65   new schema name
19030 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61   in place of "ma
19040 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a  in".  ^SQLite.**
19050 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61   does not make a
19060 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77   copy of the new
19070 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d   main schema nam
19080 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65  e string, so the
19090 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
190a0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
190b0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61   the argument pa
190c0 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44  ssed into this D
190d0 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69  BCONFIG option i
190e0 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75  s unchanged.** u
190f0 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64  ntil after the d
19100 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19110 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f  on closes..** </
19120 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
19130 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
19140 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f  _CKPT_ON_CLOSE</
19150 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61  dt>.** <dd> Usua
19160 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61  lly, when a data
19170 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65  base in wal mode
19180 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65   is closed or de
19190 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a  tached from a .*
191a0 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * database handl
191b0 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73  e, SQLite checks
191c0 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65   if this will me
191d0 61 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72  an that there ar
191e0 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e  e now no .** con
191f0 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20  nections at all 
19200 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  to the database.
19210 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f   If so, it perfo
19220 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74  rms a checkpoint
19230 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62   .** operation b
19240 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68  efore closing th
19250 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68  e connection. Th
19260 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65  is option may be
19270 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72   used to.** over
19280 72 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69  ride this behavi
19290 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70  our. The first p
192a0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
192b0 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f  to this operatio
192c0 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67  n.** is an integ
192d0 65 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f  er - non-zero to
192e0 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f   disable checkpo
192f0 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f  ints-on-close, o
19300 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64  r zero (the.** d
19310 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c  efault) to enabl
19320 65 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f  e them. The seco
19330 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
19340 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
19350 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20  integer.** into 
19360 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e  which is written
19370 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
19380 61 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63  ate whether chec
19390 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65  kpoints-on-close
193a0 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69  .** have been di
193b0 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68  sabled - 0 if th
193c0 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62  ey are not disab
193d0 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61  led, 1 if they a
193e0 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  re..** </dd>.**.
193f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
19400 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50  CONFIG_ENABLE_QP
19410 53 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  SG</dt>.** <dd>^
19420 28 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  (The SQLITE_DBCO
19430 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47  NFIG_ENABLE_QPSG
19440 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65   option activate
19450 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73  s or deactivates
19460 0a 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70  .** the [query p
19470 6c 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79  lanner stability
19480 20 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53   guarantee] (QPS
19490 47 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50  G).  When the QP
194a0 53 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a  SG is active,.**
194b0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75   a single SQL qu
194c0 65 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ery statement wi
194d0 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68  ll always use th
194e0 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
194f0 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
19500 66 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75  f values of [bou
19510 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  nd parameters].)
19520 5e 20 54 68 65 20 51 50 53 47 20 64 69 73 61 62  ^ The QPSG disab
19530 6c 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f  les some query o
19540 70 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20  ptimizations.** 
19550 74 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65  that look at the
19560 20 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64   values of bound
19570 20 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69   parameters, whi
19580 63 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65  ch can make some
19590 20 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77   queries.** slow
195a0 65 72 2e 20 20 42 75 74 20 74 68 65 20 51 50 53  er.  But the QPS
195b0 47 20 68 61 73 20 74 68 65 20 61 64 76 61 6e 74  G has the advant
195c0 61 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64  age of more pred
195d0 69 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72  ictable behavior
195e0 2e 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51  .  With.** the Q
195f0 50 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69  PSG active, SQLi
19600 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75  te will always u
19610 73 65 20 74 68 65 20 73 61 6d 65 20 71 75 65 72  se the same quer
19620 79 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69  y plan in the fi
19630 65 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73  eld as.** was us
19640 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
19650 67 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a  g in the lab..**
19660 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
19670 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
19680 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
19690 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20  INDBNAME        
196a0 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73      1000 /* cons
196b0 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69  t char* */.#defi
196c0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
196d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
196e0 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a           1001 /*
196f0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
19700 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19710 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19720 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20  _FKEY           
19730 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1002 /* int int*
19740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19750 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19760 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  LE_TRIGGER      
19770 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e    1003 /* int in
19780 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
19790 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
197a0 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
197b0 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20  ZER 1004 /* int 
197c0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
197d0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
197e0 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
197f0 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e  NSION 1005 /* in
19800 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
19810 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19820 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
19830 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20  SE      1006 /* 
19840 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
19850 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19860 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20  FIG_ENABLE_QPSG 
19870 20 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f            1007 /
19880 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
19890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
198a0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
198b0 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
198c0 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f  t Codes.** METHO
198d0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
198e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
198f0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
19900 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
19910 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
19920 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
19930 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
19940 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
19950 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
19960 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
19970 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
19980 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
19990 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
199a0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
199b0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
199c0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
199d0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
199e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
199f0 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
19a00 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Rowid.** METHOD:
19a10 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
19a20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
19a30 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
19a40 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
19a50 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
19a60 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
19a70 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
19a80 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
19a90 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
19aa0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
19ab0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
19ac0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
19ad0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
19ae0 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
19af0 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
19b00 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
19b10 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
19b20 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
19b30 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
19b40 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
19b50 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
19b60 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
19b70 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
19b80 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
19b90 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
19ba0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
19bb0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
19bc0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
19bd0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
19be0 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
19bf0 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74  face usually ret
19c00 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
19c10 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20   of.** the most 
19c20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
19c30 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
19c40 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
19c50 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
19c60 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
19c70 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49  connection D. ^I
19c80 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54  nserts into [WIT
19c90 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
19ca0 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  es are not.** re
19cb0 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73  corded. ^If no s
19cc0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
19cd0 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  T]s into rowid t
19ce0 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 20  ables have ever 
19cf0 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20  occurred .** on 
19d00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19d10 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20  nection D, then 
19d20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
19d30 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74  ert_rowid(D) ret
19d40 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a  urns .** zero..*
19d50 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20  *.** As well as 
19d60 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61  being set automa
19d70 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20  tically as rows 
19d80 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74  are inserted int
19d90 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61  o database.** ta
19da0 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  bles, the value 
19db0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
19dc0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
19dd0 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20   set explicitly 
19de0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
19df0 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
19e00 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f  owid()].**.** So
19e10 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  me virtual table
19e20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
19e30 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73   may INSERT rows
19e40 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
19e50 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  es as.** part of
19e60 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72   committing a tr
19e70 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20  ansaction (e.g. 
19e80 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 63  to flush data ac
19e90 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d  cumulated in mem
19ea0 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e  ory.** to disk).
19eb0 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 75   In this case su
19ec0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
19ed0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
19ee0 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64  return the rowid
19ef0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
19f00 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e  ith these intern
19f10 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74  al INSERT operat
19f20 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64  ions, which lead
19f30 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69  s to .** unintui
19f40 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69  tive results. Vi
19f50 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
19f60 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74  ementations that
19f70 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77   do write to row
19f80 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20  id.** tables in 
19f90 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f  this way can avo
19fa0 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20  id this problem 
19fb0 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65  by restoring the
19fc0 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f   original .** ro
19fd0 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20  wid value using 
19fe0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73  [sqlite3_set_las
19ff0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1a000 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  ] before returni
1a010 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74  ng .** control t
1a020 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a  o the user..**.*
1a030 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
1a040 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
1a050 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e 20   a trigger then 
1a060 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
1a070 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65  l .** return the
1a080 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
1a090 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 20  inserted row as 
1a0a0 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
1a0b0 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69  ger is .** runni
1a0c0 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69  ng. Once the tri
1a0d0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64  gger program end
1a0e0 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
1a0f0 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
1a100 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
1a110 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
1a120 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
1a130 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e  ger was fired.)^
1a140 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
1a150 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
1a160 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
1a170 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
1a180 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
1a190 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
1a1a0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
1a1b0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a1c0 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
1a1d0 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
1a1e0 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
1a1f0 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
1a200 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
1a210 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
1a220 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
1a230 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
1a240 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1a250 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
1a260 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
1a270 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
1a280 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
1a290 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
1a2a0 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
1a2b0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
1a2c0 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
1a2d0 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
1a2e0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
1a2f0 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
1a300 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
1a310 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
1a320 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
1a330 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
1a340 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
1a350 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
1a360 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
1a370 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
1a380 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
1a390 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
1a3a0 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
1a3b0 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
1a3c0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
1a3d0 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
1a3e0 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
1a3f0 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
1a400 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
1a410 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
1a420 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
1a430 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
1a440 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
1a450 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
1a460 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1a470 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1a480 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
1a490 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
1a4a0 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
1a4b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
1a4c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
1a4d0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a4e0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
1a4f0 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
1a500 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
1a510 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
1a520 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
1a530 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1a540 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
1a550 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
1a560 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
1a570 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
1a580 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
1a590 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
1a5a0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
1a5b0 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
1a5c0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1a5d0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1a5e0 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
1a5f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a600 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e   Set the Last In
1a610 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65  sert Rowid value
1a620 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  ..** METHOD: sql
1a630 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
1a640 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1a650 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20  insert_rowid(D, 
1a660 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73  R) method allows
1a670 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1a680 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76   to.** set the v
1a690 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1a6a0 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
1a6b0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1a6c0 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77  id(D) to R .** w
1a6d0 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67  ithout inserting
1a6e0 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20   a row into the 
1a6f0 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69  database..*/.voi
1a700 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61  d sqlite3_set_la
1a710 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a720 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33  sqlite3*,sqlite3
1a730 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _int64);../*.** 
1a740 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
1a750 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
1a760 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
1a770 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1a780 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1a790 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1a7a0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1a7b0 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65  odified, inserte
1a7c0 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d or.** deleted 
1a7d0 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
1a7e0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
1a7f0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1a800 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
1a810 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61  ment on the data
1a820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a830 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1a840 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e   only parameter.
1a850 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61  .** ^Executing a
1a860 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
1a870 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
1a880 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  oes not modify t
1a890 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
1a8a0 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
1a8b0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ction..**.** ^On
1a8c0 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
1a8d0 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  directly by the 
1a8e0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a8f0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1a900 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64  nt are.** consid
1a910 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79  ered - auxiliary
1a920 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
1a930 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  by [CREATE TRIGG
1a940 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20  ER | triggers], 
1a950 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
1a960 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45   actions] or [RE
1a970 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
1a980 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
1a990 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
1a9a0 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20   .** Changes to 
1a9b0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
1a9c0 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a  intercepted by .
1a9d0 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  ** [INSTEAD OF t
1a9e0 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44  rigger | INSTEAD
1a9f0 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72   OF triggers] ar
1aa00 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e  e not counted. ^
1aa10 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65  The value .** re
1aa20 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1aa30 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65  3_changes() imme
1aa40 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e  diately after an
1aa50 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1aa60 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74  or .** DELETE st
1aa70 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61  atement run on a
1aa80 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20   view is always 
1aa90 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67  zero. Only chang
1aaa0 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20  es made to real 
1aab0 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63  .** tables are c
1aac0 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  ounted..**.** Th
1aad0 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f  ings are more co
1aae0 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65  mplicated if the
1aaf0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1ab00 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  () function is.*
1ab10 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65  * executed while
1ab20 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1ab30 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54  am is running. T
1ab40 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69  his may happen i
1ab50 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  f the.** program
1ab60 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67   uses the [chang
1ab70 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1ab80 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f  n], or if some o
1ab90 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ther callback.**
1aba0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65   function invoke
1abb0 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  s sqlite3_change
1abc0 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73  s() directly. Es
1abd0 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a  sentially:.** .*
1abe0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
1abf0 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69   ^(Before enteri
1ac00 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  ng a trigger pro
1ac10 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72  gram the value r
1ac20 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20  eturned by.**   
1ac30 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61       sqlite3_cha
1ac40 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
1ac50 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20  is saved. After 
1ac60 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67  the trigger prog
1ac70 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68  ram .**        h
1ac80 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65  as finished, the
1ac90 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20   original value 
1aca0 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a  is restored.)^.*
1acb0 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57  * .**   <li> ^(W
1acc0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1acd0 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53  program each INS
1ace0 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20  ERT, UPDATE and 
1acf0 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20  DELETE .**      
1ad00 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73    statement sets
1ad10 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1ad20 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
1ad30 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
1ad40 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74      upon complet
1ad50 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f  ion as normal. O
1ad60 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76  f course, this v
1ad70 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e  alue will not in
1ad80 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20  clude .**       
1ad90 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72   any changes per
1ada0 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72  formed by sub-tr
1adb0 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73  iggers, as the s
1adc0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1add0 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75   .**        valu
1ade0 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20  e will be saved 
1adf0 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74  and restored aft
1ae00 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67  er each sub-trig
1ae10 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a  ger has run.)^.*
1ae20 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e  * </ul>.** .** ^
1ae30 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
1ae40 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29  if the changes()
1ae50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f   SQL function (o
1ae60 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73  r similar) is us
1ae70 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
1ae80 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  st INSERT, UPDAT
1ae90 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
1aea0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
1aeb0 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72  rigger, it .** r
1aec0 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
1aed0 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   as set when the
1aee0 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65   calling stateme
1aef0 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69  nt began executi
1af00 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ng..** ^If it is
1af10 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63   used by the sec
1af20 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ond or subsequen
1af30 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74  t such statement
1af40 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1af50 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74  r .** program, t
1af60 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1af70 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e  d reflects the n
1af80 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
1af90 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  dified by the .*
1afa0 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52  * previous INSER
1afb0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1afc0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
1afd0 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72  thin the same tr
1afe0 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  igger..**.** See
1aff0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
1b000 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1b010 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
1b020 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
1b030 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
1b040 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
1b050 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1b060 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1b070 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1b080 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1b090 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1b0a0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1b0b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1b0c0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1b0d0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
1b0e0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
1b0f0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1b100 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1b110 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1b120 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1b130 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b140 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
1b150 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1b160 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1b170 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1b180 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1b190 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  s the total numb
1b1a0 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72  er of rows inser
1b1b0 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72  ted, modified or
1b1c0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61  .** deleted by a
1b1d0 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  ll [INSERT], [UP
1b1e0 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
1b1f0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d  ] statements com
1b200 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20  pleted.** since 
1b210 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b220 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e  nection was open
1b230 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  ed, including th
1b240 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a  ose executed as.
1b250 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67  ** part of trigg
1b260 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78  er programs. ^Ex
1b270 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
1b280 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
1b290 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20  atement.** does 
1b2a0 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76  not affect the v
1b2b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1b2c0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1b2d0 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a  hanges()..** .**
1b2e0 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61   ^Changes made a
1b2f0 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69  s part of [forei
1b300 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1b310 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  are included in 
1b320 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75  the.** count, bu
1b330 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20  t those made as 
1b340 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20  part of REPLACE 
1b350 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
1b360 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74  ution are.** not
1b370 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  . ^Changes to a 
1b380 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1b390 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53  tercepted by INS
1b3a0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
1b3b0 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75   .** are not cou
1b3c0 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65  nted..** .** See
1b3d0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
1b3e0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
1b3f0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1b400 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1b410 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1b420 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
1b430 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1b440 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1b450 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1b460 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1b470 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1b480 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1b490 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1b4a0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1b4b0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1b4c0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1b4d0 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
1b4e0 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1b4f0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
1b500 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1b510 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1b520 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b530 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
1b540 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
1b550 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1b560 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
1b570 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
1b580 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
1b590 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
1b5a0 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
1b5b0 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
1b5c0 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
1b5d0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
1b5e0 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
1b5f0 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
1b600 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
1b610 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
1b620 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
1b630 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
1b640 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
1b650 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
1b660 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
1b670 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
1b680 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
1b690 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
1b6a0 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
1b6b0 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
1b6c0 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
1b6d0 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
1b6e0 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
1b6f0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
1b700 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
1b710 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
1b720 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1b730 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
1b740 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
1b750 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
1b760 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
1b770 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1b780 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
1b790 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
1b7a0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
1b7b0 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
1b7c0 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
1b7d0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
1b7e0 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
1b7f0 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
1b800 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
1b810 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
1b820 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
1b830 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
1b840 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
1b850 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
1b860 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
1b870 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
1b880 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
1b890 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
1b8a0 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
1b8b0 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
1b8c0 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
1b8d0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
1b8e0 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
1b8f0 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
1b900 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
1b910 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
1b920 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
1b930 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
1b940 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
1b950 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b960 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
1b970 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
1b980 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
1b990 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
1b9a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b9b0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
1b9c0 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
1b9d0 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
1b9e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1b9f0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1ba00 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1ba10 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1ba20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
1ba30 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
1ba40 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
1ba50 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
1ba60 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
1ba70 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
1ba80 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
1ba90 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1baa0 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
1bab0 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
1bac0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1bad0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1bae0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1baf0 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
1bb00 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
1bb10 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
1bb20 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1bb30 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
1bb40 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
1bb50 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
1bb60 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
1bb70 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
1bb80 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1bb90 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
1bba0 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
1bbb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1bbc0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1bbd0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1bbe0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bbf0 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
1bc00 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1bc10 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
1bc20 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1bc30 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
1bc40 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
1bc50 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
1bc60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1bc70 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
1bc80 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
1bc90 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
1bca0 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
1bcb0 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
1bcc0 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
1bcd0 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
1bce0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
1bcf0 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
1bd00 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
1bd10 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
1bd20 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
1bd30 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
1bd40 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
1bd50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
1bd60 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
1bd70 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
1bd80 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
1bd90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
1bda0 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
1bdb0 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
1bdc0 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
1bdd0 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
1bde0 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
1bdf0 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
1be00 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
1be10 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
1be20 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
1be30 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
1be40 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
1be50 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
1be60 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
1be70 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
1be80 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
1be90 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
1bea0 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
1beb0 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
1bec0 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
1bed0 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
1bee0 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
1bef0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
1bf00 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
1bf10 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
1bf20 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
1bf30 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
1bf40 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
1bf50 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
1bf60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1bf70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
1bf80 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
1bf90 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
1bfa0 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
1bfb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
1bfc0 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
1bfd0 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
1bfe0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1bff0 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
1c000 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
1c010 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
1c020 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
1c030 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
1c040 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
1c050 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
1c060 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
1c070 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
1c080 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1c090 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
1c0a0 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
1c0b0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1c0c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
1c0d0 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
1c0e0 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
1c0f0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
1c100 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
1c110 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
1c120 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
1c130 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
1c140 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
1c150 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c160 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
1c170 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
1c180 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1c190 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
1c1a0 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
1c1b0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
1c1c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
1c1d0 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
1c1e0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1c1f0 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
1c200 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
1c210 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1c220 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
1c230 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
1c240 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
1c250 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
1c260 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
1c270 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
1c280 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
1c290 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
1c2a0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
1c2b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
1c2c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c2d0 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
1c2e0 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
1c2f0 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
1c300 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
1c310 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61  {busy-handler ca
1c320 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61  llback} {busy ha
1c330 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  ndler}.** METHOD
1c340 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1c350 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73  ^The sqlite3_bus
1c360 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29  y_handler(D,X,P)
1c370 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1c380 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c390 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68  n X.** that migh
1c3a0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1c3b0 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
1c3c0 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
1c3d0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61  mpt is made to a
1c3e0 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65  ccess a database
1c3f0 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65   table associate
1c400 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62  d with.** [datab
1c410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1c420 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74  D when another t
1c430 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
1c440 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c  ess has the tabl
1c450 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65  e locked..** The
1c460 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1c470 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63  ndler() interfac
1c480 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70  e is used to imp
1c490 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74  lement.** [sqlit
1c4a0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1c4b0 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62  )] and [PRAGMA b
1c4c0 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a  usy_timeout]..**
1c4d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
1c4e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1c4f0 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
1c500 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75  BUSY].** is retu
1c510 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
1c520 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
1c530 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
1c540 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1c550 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
1c560 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
1c570 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
1c580 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
1c590 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
1c5a0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
1c5b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
1c5c0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
1c5d0 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
1c5e0 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
1c5f0 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
1c600 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1c610 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1c620 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
1c630 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
1c640 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
1c650 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1c660 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
1c670 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
1c680 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
1c690 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75   invoked previou
1c6a0 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65  sly for the same
1c6b0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
1c6c0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
1c6d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1c6e0 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
1c6f0 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
1c700 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
1c710 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1c720 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
1c730 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65  BUSY] is returne
1c740 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  d.** to the appl
1c750 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  ication..** ^If 
1c760 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1c770 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1c780 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
1c790 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
1c7a0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
1c7b0 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79  abase and the cy
1c7c0 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
1c7d0 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
1c7e0 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
1c7f0 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
1c800 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
1c810 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
1c820 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
1c830 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
1c840 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
1c850 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
1c860 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
1c870 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
1c880 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
1c890 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
1c8a0 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
1c8b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1c8c0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1c8d0 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  on instead of in
1c8e0 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62  voking the .** b
1c8f0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
1c900 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
1c910 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
1c920 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1c930 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
1c940 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
1c950 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
1c960 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1c970 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
1c980 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1c990 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
1c9a0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
1c9b0 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
1c9c0 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
1c9d0 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
1c9e0 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
1c9f0 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
1ca00 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1ca10 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
1ca20 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
1ca30 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
1ca40 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
1ca50 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1ca60 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
1ca70 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
1ca80 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
1ca90 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
1caa0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
1cab0 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
1cac0 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
1cad0 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
1cae0 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
1caf0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1cb00 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
1cb10 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
1cb20 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
1cb30 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
1cb40 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
1cb50 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
1cb60 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
1cb70 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
1cb80 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
1cb90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1cba0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  L..**.** ^(There
1cbb0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1cbc0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1cbd0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
1cbe0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
1cbf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
1cc00 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
1cc10 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
1cc20 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
1cc30 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
1cc40 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
1cc50 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
1cc60 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
1cc70 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20  * or evaluating 
1cc80 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1cc90 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61  eout=N] will cha
1cca0 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  nge the.** busy 
1ccb0 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73  handler and thus
1ccc0 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69   clear any previ
1ccd0 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68  ously set busy h
1cce0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
1ccf0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1cd00 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
1cd10 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
1cd20 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
1cd30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cd40 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1cd50 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1cd60 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  r.  In other wor
1cd70 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ds,.** the busy 
1cd80 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72  handler is not r
1cd90 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73  eentrant.  Any s
1cda0 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
1cdb0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
1cdc0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
1cdd0 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
1cde0 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
1cdf0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1ce00 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
1ce10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ce20 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
1ce30 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1ce40 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
1ce50 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1ce60 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28  sqlite3*,int(*)(
1ce70 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a  void*,int),void*
1ce80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ce90 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
1cea0 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44  imeout.** METHOD
1ceb0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1cec0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
1ced0 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
1cee0 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
1cef0 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
1cf00 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
1cf10 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
1cf20 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
1cf30 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
1cf40 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
1cf50 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
1cf60 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
1cf70 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
1cf80 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1cf90 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
1cfa0 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
1cfb0 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
1cfc0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1cfd0 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
1cfe0 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
1cff0 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
1d000 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
1d010 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
1d020 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
1d030 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1d040 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1d050 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
1d060 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
1d070 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
1d080 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
1d090 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
1d0a0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1d0b0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1d0c0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
1d0d0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1d0e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d0f0 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20  n] at any given 
1d100 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
1d110 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1d120 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
1d130 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
1d140 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
1d150 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
1d160 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
1d170 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
1d180 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
1d190 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  leared.)^.**.** 
1d1a0 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47  See also:  [PRAG
1d1b0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
1d1c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d1d0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
1d1e0 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
1d1f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d200 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
1d210 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
1d220 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54  g Queries.** MET
1d230 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1d240 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67  ** This is a leg
1d250 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  acy interface th
1d260 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20  at is preserved 
1d270 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1d280 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
1d290 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  Use of this inte
1d2a0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63  rface is not rec
1d2b0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
1d2c0 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
1d2d0 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
1d2e0 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
1d2f0 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
1d300 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
1d310 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d320 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
1d330 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
1d340 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
1d350 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
1d360 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
1d370 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
1d380 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
1d390 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
1d3a0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1d3b0 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
1d3c0 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
1d3d0 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
1d3e0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1d3f0 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
1d400 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
1d410 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
1d420 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
1d430 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1d440 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
1d450 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1d460 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
1d470 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
1d480 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
1d490 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
1d4a0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1d4b0 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
1d4c0 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
1d4d0 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
1d4e0 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
1d4f0 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
1d500 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1d510 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1d520 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
1d530 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
1d540 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
1d550 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
1d560 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
1d570 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
1d580 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
1d590 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
1d5a0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
1d5b0 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
1d5c0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
1d5d0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1d5e0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
1d5f0 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
1d600 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1d610 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
1d620 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
1d630 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
1d640 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
1d650 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
1d660 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
1d670 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
1d680 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
1d690 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1d6a0 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
1d6b0 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
1d6c0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
1d6d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
1d6e0 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
1d6f0 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65   ^(As an example
1d700 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1d710 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
1d720 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
1d730 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
1d740 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1d750 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1d760 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
1d770 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
1d780 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
1d790 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
1d7a0 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
1d7b0 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
1d7c0 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
1d7d0 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
1d7e0 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
1d7f0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d800 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
1d810 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
1d820 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
1d830 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
1d840 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
1d850 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
1d860 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
1d870 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d880 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
1d890 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
1d8a0 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
1d8b0 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
1d8c0 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
1d8d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1d8e0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
1d8f0 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
1d900 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
1d910 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
1d920 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
1d930 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d940 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
1d950 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1d960 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
1d970 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1d980 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
1d990 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
1d9a0 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
1d9b0 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
1d9c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
1d9d0 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
1d9e0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1d9f0 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
1da00 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1da10 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1da20 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1da30 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
1da40 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
1da50 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
1da60 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
1da70 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
1da80 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1da90 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
1daa0 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
1dab0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
1dac0 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
1dad0 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
1dae0 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
1daf0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
1db00 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
1db10 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
1db20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
1db30 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
1db40 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1db50 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61  ),.** it must pa
1db60 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
1db70 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
1db80 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1db90 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
1dba0 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
1dbb0 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
1dbc0 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
1dbd0 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
1dbe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
1dbf0 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
1dc00 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
1dc10 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
1dc20 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
1dc30 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
1dc40 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
1dc50 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
1dc60 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
1dc70 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1dc80 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
1dc90 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1dca0 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
1dcb0 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
1dcc0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1dcd0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
1dce0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
1dcf0 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
1dd00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1dd10 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
1dd20 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
1dd30 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
1dd40 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
1dd50 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
1dd60 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
1dd70 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
1dd80 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
1dd90 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
1dda0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
1ddb0 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
1ddc0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
1ddd0 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
1dde0 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
1ddf0 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
1de00 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
1de10 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
1de20 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
1de30 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1de40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
1de50 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
1de60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1de70 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1de80 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
1de90 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1dea0 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
1deb0 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
1dec0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1ded0 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
1dee0 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
1def0 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
1df00 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
1df10 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
1df20 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
1df30 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
1df40 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
1df50 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1df60 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
1df70 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
1df80 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
1df90 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
1dfa0 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
1dfb0 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
1dfc0 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
1dfd0 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
1dfe0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
1dff0 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1e000 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1e010 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1e020 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1e030 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1e040 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1e050 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1e060 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1e070 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1e080 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1e090 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1e0a0 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72  rary..** These r
1e0b0 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61  outines understa
1e0c0 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63  nd most of the c
1e0d0 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74  ommon K&R format
1e0e0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a  ting options,.**
1e0f0 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74   plus some addit
1e100 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61  ional non-standa
1e110 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61  rd formats, deta
1e120 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e  iled below..** N
1e130 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66  ote that some of
1e140 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72   the more obscur
1e150 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  e formatting opt
1e160 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74  ions from recent
1e170 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74  .** C-library st
1e180 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74  andards are omit
1e190 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d  ted from this im
1e1a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a  plementation..**
1e1b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e1c0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1e1d0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1e1e0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1e1f0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1e200 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1e210 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1e220 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1e230 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1e240 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1e250 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1e260 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1e270 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1e280 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1e290 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1e2a0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1e2b0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1e2c0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1e2d0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1e2e0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1e2f0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1e300 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1e310 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1e320 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1e330 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1e340 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1e350 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1e360 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1e370 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1e380 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1e390 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1e3a0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1e3b0 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1e3c0 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1e3d0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1e3e0 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1e3f0 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1e400 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1e410 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1e420 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1e430 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1e440 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1e450 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1e460 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1e470 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1e480 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1e490 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1e4a0 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1e4b0 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1e4c0 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1e4d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1e4e0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1e4f0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1e500 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1e510 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1e520 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1e530 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1e540 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1e550 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1e560 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1e570 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1e580 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1e590 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1e5a0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1e5b0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1e5c0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1e5d0 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1e5e0 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1e5f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1e600 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1e610 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1e620 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1e630 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1e640 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1e650 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1e660 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1e670 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1e680 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1e690 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1e6a0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1e6b0 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1e6c0 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1e6d0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1e6e0 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1e6f0 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1e700 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1e710 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1e720 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1e730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e740 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1e750 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1e760 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1e770 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1e780 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1e790 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1e7a0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1e7b0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1e7c0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1e7d0 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1e7e0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1e7f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1e800 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1e810 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1e820 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1e830 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1e840 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1e850 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22  re "%q", "%Q", "
1e860 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  %w" and "%z" opt
1e870 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1e880 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1e890 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1e8a0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1e8b0 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1e8c0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1e8d0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1e8e0 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1e8f0 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1e900 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1e910 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1e920 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1e930 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1e940 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1e950 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1e960 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1e970 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1e980 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1e990 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1e9a0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1e9b0 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1e9c0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1e9d0 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1e9e0 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1e9f0 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1ea00 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ea10 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1ea20 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1ea30 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1ea40 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1ea50 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1ea60 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1ea70 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1ea80 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1ea90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1eaa0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1eab0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1eac0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1ead0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1eae0 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1eaf0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1eb00 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1eb10 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1eb20 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1eb30 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1eb40 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1eb50 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1eb60 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1eb70 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1eb80 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1eb90 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1eba0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1ebb0 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1ebc0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1ebd0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1ebe0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1ebf0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1ec00 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1ec10 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1ec20 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1ec30 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1ec40 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1ec50 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1ec60 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1ec70 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1ec80 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1ec90 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1eca0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1ecb0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1ecc0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1ecd0 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1ece0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1ecf0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1ed00 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1ed10 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1ed20 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1ed30 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1ed40 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1ed50 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1ed60 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1ed70 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1ed80 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1ed90 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1eda0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1edb0 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1edc0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1edd0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1ede0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1edf0 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1ee00 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1ee10 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1ee20 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1ee30 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1ee40 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1ee50 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1ee60 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1ee70 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1ee80 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1ee90 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1eea0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1eeb0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1eec0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1eed0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1eee0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1eef0 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1ef00 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1ef10 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1ef20 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1ef30 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1ef40 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1ef50 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1ef60 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1ef70 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1ef80 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1ef90 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1efa0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1efb0 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1efc0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1efd0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1efe0 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d   ^(The "%w" form
1eff0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73  atting option is
1f000 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70   like "%q" excep
1f010 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74  t that it expect
1f020 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61  s to.** be conta
1f030 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62  ined within doub
1f040 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61  le-quotes instea
1f050 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74  d of single quot
1f060 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73  es, and it.** es
1f070 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65  capes the double
1f080 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72  -quote character
1f090 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1f0a0 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20  single-quote.** 
1f0b0 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68  character.)^  Th
1f0c0 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1f0d0 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65  g option is inte
1f0e0 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20  nded for safely 
1f0f0 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62  inserting.** tab
1f100 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61  le and column na
1f110 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74  mes into a const
1f120 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65  ructed SQL state
1f130 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ment..**.** ^(Th
1f140 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1f150 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1f160 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1f170 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1f180 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1f190 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1f1a0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1f1b0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1f1c0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1f1d0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1f1e0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1f1f0 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
1f200 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1f210 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1f220 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1f230 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1f240 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1f250 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
1f260 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1f270 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1f280 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1f290 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
1f2a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1f2b0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
1f2c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1f2d0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
1f2e0 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
1f2f0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
1f300 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
1f310 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
1f320 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
1f330 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
1f340 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
1f350 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
1f360 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
1f370 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
1f380 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
1f390 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
1f3a0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1f3b0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
1f3c0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
1f3d0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
1f3e0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
1f3f0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
1f400 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f410 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
1f420 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1f430 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
1f440 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
1f450 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
1f460 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
1f470 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
1f480 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1f490 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
1f4a0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
1f4b0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
1f4c0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
1f4d0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1f4e0 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
1f4f0 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
1f500 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1f510 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
1f520 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
1f530 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
1f540 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1f550 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
1f560 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1f570 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73  N) routine works
1f580 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71   just like.** sq
1f590 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
1f5a0 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
1f5b0 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d   an unsigned 64-
1f5c0 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74  bit integer inst
1f5d0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e  ead.** of a sign
1f5e0 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  ed 32-bit intege
1f5f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
1f600 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
1f610 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
1f620 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1f630 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1f640 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1f650 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1f660 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
1f670 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
1f680 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
1f690 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1f6a0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
1f6b0 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
1f6c0 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
1f6d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1f6e0 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
1f6f0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
1f700 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1f710 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
1f720 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
1f730 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
1f740 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
1f750 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
1f760 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
1f770 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
1f780 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
1f790 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
1f7a0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
1f7b0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1f7c0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
1f7d0 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
1f7e0 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
1f7f0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1f800 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
1f810 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
1f820 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
1f830 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
1f840 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
1f850 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
1f860 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1f870 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1f880 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
1f890 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f8a0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74  realloc(X,N) int
1f8b0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1f8c0 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1f8d0 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1f8e0 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61  cation X to be a
1f8f0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e  t least N bytes.
1f900 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61  .** ^If the X pa
1f910 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1f920 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a  e3_realloc(X,N).
1f930 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
1f940 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
1f950 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
1f960 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
1f970 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1f980 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  (N)..** ^If the 
1f990 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  N parameter to s
1f9a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f9b0 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  ,N) is zero or.*
1f9c0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
1f9d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1f9e0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
1f9f0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
1fa00 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a  qlite3_free(X)..
1fa10 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
1fa20 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1fa30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1fa40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1fa50 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1fa60 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1fa70 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75   or NULL if insu
1fa80 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1fa90 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
1faa0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1fab0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1fac0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1fad0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1fae0 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1faf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1fb00 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1fb10 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1fb20 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1fb30 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1fb40 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70  c(X,N) and the p
1fb50 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1fb60 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
1fb70 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fb80 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55  (X,N) returns NU
1fb90 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69  LL and N is posi
1fba0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a  tive, then the.*
1fbb0 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  * prior allocati
1fbc0 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  on is not freed.
1fbd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1fbe0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c  te3_realloc64(X,
1fbf0 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  N) interfaces wo
1fc00 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a  rks the same as.
1fc10 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
1fc20 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74  oc(X,N) except t
1fc30 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69  hat N is a 64-bi
1fc40 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
1fc50 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
1fc60 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64   a 32-bit signed
1fc70 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
1fc80 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72  ^If X is a memor
1fc90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65  y allocation pre
1fca0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
1fcb0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1fcc0 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1fcd0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73  e3_malloc64(), s
1fce0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1fcf0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  , or sqlite3_rea
1fd00 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a  lloc64(), then.*
1fd10 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1fd20 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  X) returns the s
1fd30 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f  ize of that memo
1fd40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e  ry allocation in
1fd50 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20   bytes..** ^The 
1fd60 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1fd70 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  y sqlite3_msize(
1fd80 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  X) might be larg
1fd90 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62  er than the numb
1fda0 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72  er.** of bytes r
1fdb0 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20  equested when X 
1fdc0 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20  was allocated.  
1fdd0 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20  ^If X is a NULL 
1fde0 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
1fdf0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1fe00 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20   returns zero.  
1fe10 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73  If X points to s
1fe20 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73  omething that is
1fe30 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69   not.** the begi
1fe40 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20  nning of memory 
1fe50 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69  allocation, or i
1fe60 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  f it points to a
1fe70 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c   formerly.** val
1fe80 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  id memory alloca
1fe90 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f  tion that has no
1fea0 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68  w been freed, th
1feb0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
1fec0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73  ** of sqlite3_ms
1fed0 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69  ize(X) is undefi
1fee0 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ned and possibly
1fef0 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
1ff00 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
1ff10 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1ff20 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65  malloc(), sqlite
1ff30 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  3_realloc(),.** 
1ff40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1ff50 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
1ff60 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69  realloc64().** i
1ff70 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1ff80 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1ff90 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1ffa0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1ffb0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1ffc0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1ffd0 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1ffe0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1fff0 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
20000 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
20010 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
20020 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
20030 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
20040 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
20050 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
20060 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
20070 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
20080 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
20090 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
200a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
200b0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
200c0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
200d0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
200e0 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
200f0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
20100 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
20110 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
20120 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
20130 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
20140 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
20150 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
20160 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
20170 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
20180 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
20190 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
201a0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
201b0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
201c0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
201d0 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
201e0 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
201f0 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
20200 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
20210 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
20220 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
20230 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
20240 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
20250 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
20260 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
20270 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
20280 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
20290 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
202a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
202b0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
202c0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
202d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
202e0 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
202f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
20300 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
20310 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
20320 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
20330 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
20340 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
20350 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
20360 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
20370 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
20380 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
20390 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
203a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
203b0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
203c0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
203d0 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
203e0 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
203f0 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
20400 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
20410 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
20420 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
20430 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
20440 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
20450 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
20460 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74  3_malloc64(sqlit
20470 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
20480 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
20490 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
204a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
204b0 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71  lloc64(void*, sq
204c0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
204d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
204e0 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33  (void*);.sqlite3
204f0 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
20500 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  msize(void*);../
20510 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
20520 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
20530 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
20540 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
20550 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
20560 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
20570 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
20580 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
20590 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
205a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
205b0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
205c0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
205d0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
205e0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
205f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20600 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
20610 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
20620 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
20630 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
20640 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
20650 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
20660 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
20670 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
20680 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
20690 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
206a0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
206b0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
206c0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
206d0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
206e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
206f0 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
20700 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
20710 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
20720 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
20730 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
20740 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20750 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
20760 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20770 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
20780 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
20790 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
207a0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
207b0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
207c0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
207d0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
207e0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
207f0 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
20800 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
20810 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
20820 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
20830 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
20840 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
20850 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
20860 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
20870 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
20880 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
20890 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
208a0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
208b0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
208c0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
208d0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
208e0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
208f0 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
20900 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20910 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
20920 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
20930 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
20940 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
20950 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
20960 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
20970 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
20980 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
20990 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
209a0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
209b0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
209c0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
209d0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
209e0 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
209f0 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
20a00 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
20a10 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
20a20 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
20a30 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
20a40 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
20a50 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
20a60 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
20a70 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
20a80 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
20a90 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
20aa0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
20ab0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
20ac0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
20ad0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
20ae0 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
20af0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
20b00 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
20b10 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
20b20 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
20b30 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
20b40 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
20b50 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
20b60 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
20b70 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
20b80 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
20b90 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54   buffer P..** ^T
20ba0 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63  he P parameter c
20bb0 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  an be a NULL poi
20bc0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  nter..**.** ^If 
20bd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73  this routine has
20be0 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f   not been previo
20bf0 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69  usly called or i
20c00 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a  f the previous.*
20c10 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73  * call had N les
20c20 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20  s than one or a 
20c30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
20c40 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e   P, then the PRN
20c50 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75  G is.** seeded u
20c60 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
20c70 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
20c80 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
20c90 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64  thod of.** the d
20ca0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
20cb0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
20cc0 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73  ^If the previous
20cd0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
20ce0 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f  utine had an N o
20cf0 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20  f 1 or more and 
20d00 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20  a.** non-NULL P 
20d10 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d  then the pseudo-
20d20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
20d30 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
20d40 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
20d50 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
20d60 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
20d70 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
20d80 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
20d90 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
20da0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
20db0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20dc0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
20dd0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
20de0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
20df0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b  OD: sqlite3.** K
20e00 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72  EYWORDS: {author
20e10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a  izer callback}.*
20e20 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
20e30 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
20e40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20e50 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
20e60 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
20e70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
20e80 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
20e90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
20ea0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
20eb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
20ec0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
20ed0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
20ee0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
20ef0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
20f00 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
20f10 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
20f20 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
20f30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20f40 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v3()], [sqlite
20f50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
20f60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20f70 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64  16_v2()],.** and
20f80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20f90 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20  e16_v3()].  ^At 
20fa0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
20fb0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
20fc0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
20fd0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
20fe0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
20ff0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
21000 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
21010 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21020 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
21030 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
21040 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
21050 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
21060 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21070 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
21080 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
21090 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
210a0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
210b0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
210c0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
210d0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
210e0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
210f0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
21100 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
21110 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
21120 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
21130 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
21140 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
21150 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
21160 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
21170 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21180 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
21190 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
211a0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
211b0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
211c0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
211d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
211e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
211f0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
21200 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
21210 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
21220 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
21230 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
21240 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
21250 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
21260 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
21270 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
21280 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
21290 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
212a0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
212b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
212c0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
212d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
212e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
212f0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
21300 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
21310 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
21320 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
21330 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
21340 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
21350 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
21360 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
21370 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
21380 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
21390 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
213a0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
213b0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
213c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
213d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
213e0 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
213f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
21400 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
21410 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
21420 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
21430 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
21440 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
21450 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
21460 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
21470 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
21480 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
21490 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
214a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
214b0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f  e either NULL po
214c0 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74  inters or zero-t
214d0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
214e0 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69  s.** that contai
214f0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74  n additional det
21500 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
21510 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
21520 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69  orized..** Appli
21530 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77  cations must alw
21540 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20  ays be prepared 
21550 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e  to encounter a N
21560 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61  ULL pointer in a
21570 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69  ny.** of the thi
21580 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73  rd through the s
21590 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  ixth parameters 
215a0 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  of the authoriza
215b0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
215c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
215d0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
215e0 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
215f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
21600 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
21610 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
21620 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
21630 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
21640 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
21650 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
21660 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
21670 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
21680 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
21690 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
216a0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
216b0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
216c0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
216d0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
216e0 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
216f0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
21700 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
21710 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
21720 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
21730 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57  f a table..** ^W
21740 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72  hen a table is r
21750 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b  eferenced by a [
21760 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63  SELECT] but no c
21770 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65  olumn values are
21780 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72  .** extracted fr
21790 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66  om that table (f
217a0 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20  or example in a 
217b0 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53  query like.** "S
217c0 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46  ELECT count(*) F
217d0 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74  ROM tab") then t
217e0 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  he [SQLITE_READ]
217f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21800 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  back.** is invok
21810 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74  ed once for that
21820 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f   table with a co
21830 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69  lumn name that i
21840 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
21850 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  g..** ^If the ac
21860 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
21870 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
21880 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
21890 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
218a0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
218b0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
218c0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
218d0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
218e0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
218f0 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
21900 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
21910 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
21920 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
21930 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
21940 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
21950 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
21960 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
21970 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
21980 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
21990 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
219a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
219b0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
219c0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
219d0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
219e0 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
219f0 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
21a00 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
21a10 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
21a20 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
21a30 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
21a40 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
21a50 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
21a60 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
21a70 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
21a80 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
21a90 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
21aa0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
21ab0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
21ac0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
21ad0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
21ae0 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
21af0 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
21b00 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
21b10 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
21b20 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
21b30 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
21b40 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
21b50 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
21b60 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
21b70 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
21b80 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
21b90 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
21ba0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
21bb0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
21bc0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
21bd0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
21be0 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
21bf0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
21c00 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
21c10 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
21c20 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
21c30 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
21c40 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
21c50 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
21c60 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
21c70 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
21c80 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
21c90 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
21ca0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
21cb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
21cc0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
21cd0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
21ce0 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
21cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
21d00 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
21d10 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
21d20 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21d30 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
21d40 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
21d50 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
21d60 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
21d70 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
21d80 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
21d90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
21da0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
21db0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
21dc0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21dd0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
21de0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
21df0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
21e00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21e10 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
21e20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21e30 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
21e40 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
21e50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
21e60 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
21e70 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
21e80 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
21e90 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
21ea0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
21eb0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
21ec0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
21ed0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
21ee0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
21ef0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
21f00 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
21f10 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
21f20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
21f30 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
21f40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
21f50 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
21f60 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
21f70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
21f80 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
21f90 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
21fa0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
21fb0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
21fc0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
21fd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
21fe0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
21ff0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
22000 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
22010 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
22020 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
22030 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
22040 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
22050 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
22060 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
22070 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
22080 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
22090 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
220a0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
220b0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
220c0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
220d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
220e0 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
220f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
22100 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
22110 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
22120 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
22130 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
22140 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
22150 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
22160 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
22170 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
22180 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
22190 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
221a0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
221b0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
221c0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
221d0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
221e0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
221f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
22200 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
22210 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
22220 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
22230 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
22240 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
22250 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
22260 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
22270 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
22280 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
22290 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
222a0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
222b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
222c0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
222d0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
222e0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
222f0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
22300 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
22310 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
22320 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
22330 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69  sed as a [confli
22340 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f  ct resolution mo
22350 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  de].** returned 
22360 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
22370 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
22380 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
22390 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
223a0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
223b0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
223c0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
223d0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
223e0 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
223f0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
22400 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
22410 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
22420 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
22430 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
22440 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
22450 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
22460 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
22470 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
22480 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
22490 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
224a0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
224b0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
224c0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
224d0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
224e0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
224f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
22500 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
22510 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
22520 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
22530 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
22540 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
22550 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
22560 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
22570 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
22580 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22590 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
225a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
225b0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
225c0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
225d0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
225e0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
225f0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
22600 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
22610 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
22620 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
22630 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
22640 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
22650 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
22660 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
22670 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
22680 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
22690 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
226a0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
226b0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
226c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
226d0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
226e0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
226f0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
22700 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
22710 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
22720 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
22730 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22740 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
22750 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
22760 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
22770 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
22780 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
22790 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
227a0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
227b0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
227c0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
227d0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
227e0 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
227f0 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
22800 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22810 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
22820 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
22830 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
22840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22850 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
22860 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
22870 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
22880 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
228a0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
228b0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
228c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
228d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
228e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
228f0 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
22900 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
22910 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
22920 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22930 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22940 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
22950 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
22960 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22970 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22980 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22990 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
229a0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
229b0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
229c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
229d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
229e0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
229f0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
22a00 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22a10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22a20 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22a30 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
22a40 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22a50 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22a60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22a70 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
22a80 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
22a90 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
22aa0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22ab0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22ac0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
22ad0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
22ae0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22af0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22b00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22b10 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
22b20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
22b30 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
22b40 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22b50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22b60 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
22b70 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
22b80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22b90 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22ba0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22bb0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
22bc0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
22bd0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22be0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22bf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22c00 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
22c10 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
22c20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22c30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22c50 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
22c60 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
22c70 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22c80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22ca0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
22cb0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
22cc0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
22cd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22ce0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22cf0 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
22d00 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
22d10 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
22d20 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22d40 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
22d50 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
22d60 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
22d70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22d80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
22d90 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
22da0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
22db0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22dc0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22dd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
22de0 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
22df0 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
22e00 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
22e10 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
22e20 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
22e30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22e40 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
22e50 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
22e60 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
22e70 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
22e80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
22e90 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
22ea0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22eb0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22ec0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
22ed0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
22ee0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
22ef0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22f00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22f10 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
22f20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
22f30 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22f40 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
22f50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22f60 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
22f70 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
22f80 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
22f90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22fa0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22fb0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
22fc0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
22fd0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
22fe0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22ff0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23000 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
23010 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
23020 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
23030 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
23040 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23050 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
23060 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
23070 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
23080 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23090 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
230a0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
230b0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
230c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
230d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
230e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
230f0 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
23100 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
23110 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
23120 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
23130 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23140 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
23150 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
23160 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
23170 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
23180 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23190 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
231a0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
231b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
231c0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
231d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
231e0 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
231f0 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
23200 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
23210 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
23220 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
23230 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
23240 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
23250 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
23260 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55  fine SQLITE_RECU
23270 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  RSIVE           
23280 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   33   /* NULL   
23290 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
232a0 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a           */../*.
232b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
232c0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
232d0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ng Functions.** 
232e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
232f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
23300 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61  ines are depreca
23310 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71  ted. Use the [sq
23320 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
23330 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
23340 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f  nstead of the ro
23350 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64  utines described
23360 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
23370 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
23380 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
23390 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
233a0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
233b0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
233c0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
233d0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
233e0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
233f0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
23400 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
23410 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
23420 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
23430 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
23440 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
23450 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
23460 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
23470 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
23480 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
23490 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
234a0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
234b0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
234c0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
234d0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
234e0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
234f0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
23500 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
23510 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
23520 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
23530 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
23540 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
23550 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
23560 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
23570 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
23580 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
23590 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
235a0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
235b0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
235c0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
235d0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
235e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
235f0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
23600 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
23610 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
23620 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
23630 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
23640 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
23650 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
23660 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
23670 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
23680 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
23690 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
236a0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
236b0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
236c0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
236d0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
236e0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
236f0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
23700 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
23710 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
23720 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
23730 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
23740 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
23750 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
23760 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
23770 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
23780 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
23790 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
237a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
237b0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
237c0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
237d0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
237e0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
237f0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
23800 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
23810 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
23820 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
23830 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
23840 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
23850 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
23860 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
23870 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
23880 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
23890 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
238a0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
238b0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
238c0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
238d0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
238e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
238f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52  ..*/.SQLITE_DEPR
23900 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c  ECATED void *sql
23910 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
23920 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54  e3*,.   void(*xT
23930 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
23940 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
23950 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
23960 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TED void *sqlite
23970 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
23980 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
23990 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
239a0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
239b0 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
239c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
239d0 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65  F: SQL Trace Eve
239e0 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  nt Codes.** KEYW
239f0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41  ORDS: SQLITE_TRA
23a00 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  CE.**.** These c
23a10 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66  onstants identif
23a20 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65  y classes of eve
23a30 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  nts that can be 
23a40 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69  monitored.** usi
23a50 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
23a60 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63  trace_v2()] trac
23a70 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20  ing logic.  The 
23a80 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
23a90 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  * to [sqlite3_tr
23aa0 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20  ace_v2()] is an 
23ab0 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f  OR-ed combinatio
23ac0 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  n of one or more
23ad0 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
23ae0 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20  wing constants. 
23af0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
23b00 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
23b10 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  e callback.** is
23b20 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
23b30 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
23b40 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69  .**.** New traci
23b50 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  ng constants may
23b60 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
23b70 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
23b80 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
23b90 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61  lback has four a
23ba0 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62  rguments: xCallb
23bb0 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
23bc0 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
23bd0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69   is one of the i
23be0 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65  nteger type code
23bf0 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65  s above..** ^The
23c00 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
23c10 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
23c20 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73  text pointer pas
23c30 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
23c40 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
23c50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
23c60 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65  ce_v2()]..** The
23c70 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
23c80 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
23c90 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
23ca0 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
23cb0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
23cc0 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20  TE_TRACE_STMT]] 
23cd0 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
23ce0 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _STMT</dt>.** <d
23cf0 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
23d00 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b  CE_STMT callback
23d10 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
23d20 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
23d30 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62  ement.** first b
23d40 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e  egins running an
23d50 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74  d possibly at ot
23d60 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67  her times during
23d70 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f   the.** executio
23d80 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  n of the prepare
23d90 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63  d statement, suc
23da0 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72  h as at the star
23db0 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69  t of each.** tri
23dc0 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
23dd0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
23de0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
23df0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
23e00 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
23e10 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  he X argument is
23e20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
23e30 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20  string which.** 
23e40 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65  is the unexpande
23e50 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68  d SQL text of th
23e60 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
23e70 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63  ment or an SQL c
23e80 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20  omment .** that 
23e90 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e  indicates the in
23ea0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72  vocation of a tr
23eb0 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c  igger.  ^The cal
23ec0 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74  lback can comput
23ed0 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65  e.** the same te
23ee0 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  xt that would ha
23ef0 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ve been returned
23f00 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b   by the legacy [
23f10 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
23f20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79  .** interface by
23f30 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67   using the X arg
23f40 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67  ument when X beg
23f50 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e  ins with "--" an
23f60 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73  d invoking.** [s
23f70 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
23f80 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73  sql(P)] otherwis
23f90 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
23fa0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d  E_TRACE_PROFILE]
23fb0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
23fc0 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a  CE_PROFILE</dt>.
23fd0 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
23fe0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
23ff0 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65  callback provide
24000 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  s approximately 
24010 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f  the same.** info
24020 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72  rmation as is pr
24030 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73  ovided by the [s
24040 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
24050 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  ] callback..** ^
24060 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
24070 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
24080 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24090 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
240a0 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f  ** X argument po
240b0 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74  ints to a 64-bit
240c0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
240d0 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20  s the estimated 
240e0 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  of.** the number
240f0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74   of nanosecond t
24100 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
24110 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
24120 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20  to run..** ^The 
24130 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
24140 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  FILE callback is
24150 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
24160 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  e statement fini
24170 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  shes..**.** [[SQ
24180 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d  LITE_TRACE_ROW]]
24190 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
241a0 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  E_ROW</dt>.** <d
241b0 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
241c0 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20  CE_ROW callback 
241d0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
241e0 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a  ver a prepared.*
241f0 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65  * statement gene
24200 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72  rates a single r
24210 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a  ow of result.  .
24220 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
24230 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
24240 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
24250 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
24260 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
24270 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a  t is unused..**.
24280 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
24290 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51  E_CLOSE]] <dt>SQ
242a0 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
242b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
242c0 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c   SQLITE_TRACE_CL
242d0 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  OSE callback is 
242e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64  invoked when a d
242f0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
24300 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a  ction closes..**
24310 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
24320 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
24330 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
24340 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63  onnection] objec
24350 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61  t.** and the X a
24360 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65  rgument is unuse
24370 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d..** </dl>.*/.#
24380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
24390 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30  ACE_STMT       0
243a0 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x01.#define SQLI
243b0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
243c0 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65      0x02.#define
243d0 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f   SQLITE_TRACE_RO
243e0 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64  W        0x04.#d
243f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
24400 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78  CE_CLOSE      0x
24410 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  08../*.** CAPI3R
24420 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f  EF: SQL Trace Ho
24430 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ok.** METHOD: sq
24440 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
24450 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
24460 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72  2(D,M,X,P) inter
24470 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
24480 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a   trace callback.
24490 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67  ** function X ag
244a0 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20  ainst [database 
244b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75  connection] D, u
244c0 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61  sing property ma
244d0 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74  sk M.** and cont
244e0 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20  ext pointer P.  
244f0 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61  ^If the X callba
24500 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72  ck is.** NULL or
24510 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69   if the M mask i
24520 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61  s zero, then tra
24530 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64  cing is disabled
24540 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75  .  The.** M argu
24550 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
24560 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64  he bitwise OR-ed
24570 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
24580 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ** zero or more 
24590 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63  [SQLITE_TRACE] c
245a0 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
245b0 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69  ^Each call to ei
245c0 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ther sqlite3_tra
245d0 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
245e0 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72  trace_v2() overr
245f0 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c  ides .** (cancel
24600 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c  s) any prior cal
24610 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72  ls to sqlite3_tr
24620 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
24630 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a  _trace_v2()..**.
24640 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61  ** ^The X callba
24650 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
24660 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68  enever any of th
24670 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66  e events identif
24680 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20  ied by .** mask 
24690 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69  M occur.  ^The i
246a0 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61  nteger return va
246b0 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c  lue from the cal
246c0 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74  lback is current
246d0 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74  ly.** ignored, t
246e0 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63  hough this may c
246f0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
24700 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62  releases.  Callb
24710 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ack.** implement
24720 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65  ations should re
24730 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73  turn zero to ens
24740 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61  ure future compa
24750 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
24760 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
24770 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
24780 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  h four arguments
24790 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50  : callback(T,C,P
247a0 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
247b0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
247c0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  f the [SQLITE_TR
247d0 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74  ACE].** constant
247e0 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  s to indicate wh
247f0 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  y the callback w
24800 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  as invoked..** ^
24810 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69  The C argument i
24820 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
24830 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e  context pointer.
24840 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
24850 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
24860 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
24870 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
24880 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  T..**.** The sql
24890 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20  ite3_trace_v2() 
248a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
248b0 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65  ended to replace
248c0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
248d0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
248e0 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20  e3_trace()] and 
248f0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
24900 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69  ()], both of whi
24910 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63  ch.** are deprec
24920 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ated..*/.int sql
24930 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20  ite3_trace_v2(. 
24940 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73   sqlite3*,.  uns
24950 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69  igned uMask,.  i
24960 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75  nt(*xCallback)(u
24970 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f  nsigned,void*,vo
24980 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  id*,void*),.  vo
24990 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a  id *pCtx.);../*.
249a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
249b0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
249c0 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
249d0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
249e0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
249f0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
24a00 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
24a10 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
24a20 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
24a30 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
24a40 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
24a50 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
24a60 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
24a70 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
24a80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24a90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
24aa0 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
24ab0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24ac0 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
24ad0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
24ae0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
24af0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
24b00 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
24b10 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
24b20 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
24b30 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
24b40 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
24b50 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
24b60 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
24b70 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
24b80 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
24b90 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
24ba0 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
24bb0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
24bc0 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
24bd0 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
24be0 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
24bf0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
24c00 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
24c10 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
24c20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
24c30 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
24c40 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
24c50 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
24c60 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
24c70 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
24c80 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
24c90 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
24ca0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24cb0 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
24cc0 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
24cd0 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
24ce0 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
24cf0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
24d00 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
24d10 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
24d20 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
24d30 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
24d40 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
24d50 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
24d60 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
24d70 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
24d80 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
24d90 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
24da0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
24db0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
24dc0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
24dd0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
24de0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
24df0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
24e00 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
24e10 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
24e20 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
24e30 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
24e40 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
24e50 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
24e60 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
24e70 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
24e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
24e90 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
24ea0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
24eb0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
24ec0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24ed0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
24ee0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
24ef0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
24f00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24f10 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
24f20 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
24f30 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
24f40 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
24f50 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
24f60 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
24f70 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
24f80 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
24f90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
24fa0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
24fb0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
24fc0 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
24fd0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
24fe0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
24ff0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
25000 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
25010 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
25020 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
25030 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
25040 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
25050 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
25060 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
25070 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
25080 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25090 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
250a0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
250b0 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
250c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
250d0 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
250e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
250f0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
25100 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
25110 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
25120 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
25130 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
25140 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
25150 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
25160 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
25170 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
25180 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
25190 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
251a0 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
251b0 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
251c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
251d0 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
251e0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
251f0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25200 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
25210 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
25220 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
25230 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
25240 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
25250 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
25260 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
25270 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
25280 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
25290 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
252a0 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
252b0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
252c0 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
252d0 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
252e0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
252f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
25300 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
25310 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
25320 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
25330 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
25340 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20  t encoding will 
25350 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74  be UTF-8 for dat
25360 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75  abases created u
25370 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  sing.** sqlite3_
25380 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
25390 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54  3_open_v2().  ^T
253a0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
253b0 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65  ing for database
253c0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69  s.** created usi
253d0 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  ng sqlite3_open1
253e0 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  6() will be UTF-
253f0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
25400 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
25410 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
25420 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
25430 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
25440 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
25450 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
25460 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
25470 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
25480 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
25490 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
254a0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
254b0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
254c0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
254d0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
254e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
254f0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
25500 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
25510 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
25520 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
25530 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
25540 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
25550 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
25560 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
25570 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
25580 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
25590 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
255a0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
255b0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
255c0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
255d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
255e0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
255f0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
25600 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
25610 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
25620 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
25630 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
25640 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
25650 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
25660 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
25670 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
25680 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
25690 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
256a0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
256b0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
256c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
256d0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
256e0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
256f0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
25700 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
25710 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
25720 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
25730 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
25740 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
25750 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
25760 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
25770 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
25780 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
25790 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
257a0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
257b0 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
257c0 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
257d0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
257e0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
257f0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
25800 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
25810 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
25820 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
25830 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
25840 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
25850 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
25860 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25870 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
25880 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
25890 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
258a0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
258b0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
258c0 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
258d0 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
258e0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
258f0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
25900 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
25910 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
25920 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
25930 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
25940 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
25950 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
25960 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
25970 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25980 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
25990 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
259a0 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
259b0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
259c0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
259d0 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
259e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
259f0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
25a00 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
25a10 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
25a20 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
25a30 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
25a40 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
25a50 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
25a60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
25a70 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
25a80 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
25a90 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
25aa0 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
25ab0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
25ac0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
25ad0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
25ae0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
25af0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
25b00 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
25b10 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
25b20 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
25b30 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
25b40 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
25b50 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
25b60 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
25b70 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
25b80 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
25b90 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
25ba0 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
25bb0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
25bc0 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
25bd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
25be0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
25bf0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
25c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
25c10 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
25c20 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
25c30 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
25c40 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
25c50 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
25c60 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
25c70 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
25c80 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
25c90 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
25ca0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
25cb0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
25cc0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
25cd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25ce0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
25cf0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
25d00 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
25d10 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
25d20 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
25d30 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
25d40 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25d50 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
25d60 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
25d70 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
25d80 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
25d90 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
25da0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
25db0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
25dc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25dd0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
25de0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
25df0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
25e00 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
25e10 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
25e20 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
25e30 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
25e40 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
25e50 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
25e60 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
25e70 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
25e80 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
25e90 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
25ea0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
25eb0 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
25ec0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
25ed0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
25ee0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
25ef0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
25f00 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
25f10 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
25f20 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
25f30 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
25f40 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
25f50 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
25f60 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
25f70 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
25f80 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
25f90 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
25fa0 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
25fb0 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
25fc0 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
25fd0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
25fe0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
25ff0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
26000 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
26010 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
26020 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
26030 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
26040 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
26050 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
26060 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
26070 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
26080 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
26090 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
260a0 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
260b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
260c0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
260d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
260e0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
260f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
26100 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
26110 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
26120 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
26130 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
26140 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
26150 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
26160 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
26170 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
26180 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
26190 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
261a0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
261b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
261c0 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
261d0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
261e0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
261f0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
26200 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
26210 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
26220 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
26230 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
26240 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
26250 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
26260 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
26270 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
26280 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
26290 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
262a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
262b0 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
262c0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
262d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
262e0 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c  tion..** URI fil
262f0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
26300 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
26310 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
26320 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
26330 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
26340 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
26350 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
26360 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
26370 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
26380 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
26390 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
263a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
263b0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
263c0 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
263d0 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
263e0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
263f0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
26400 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
26410 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
26420 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
26430 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
26440 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
26450 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
26460 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
26470 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
26480 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
26490 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
264a0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
264b0 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
264c0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
264d0 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
264e0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
264f0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
26500 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
26510 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
26520 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
26530 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
26540 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
26550 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
26560 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
26570 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
26580 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
26590 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
265a0 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
265b0 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
265c0 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
265d0 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
265e0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
265f0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
26600 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
26610 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
26620 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
26630 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
26640 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
26650 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
26660 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
26670 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
26680 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
26690 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
266a0 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
266b0 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
266c0 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
266d0 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
266e0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
266f0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
26700 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
26710 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
26720 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
26730 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
26740 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
26750 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
26760 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
26770 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
26780 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
26790 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
267a0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
267b0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
267c0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
267d0 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
267e0 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
267f0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
26800 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
26810 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
26820 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
26830 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
26840 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
26850 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
26860 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
26870 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
26880 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26890 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
268a0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
268b0 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
268c0 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
268d0 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
268e0 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
268f0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
26900 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
26910 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
26920 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26930 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
26940 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
26950 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
26960 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
26970 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
26980 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
26990 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
269a0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
269b0 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
269c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
269d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
269e0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
269f0 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
26a00 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
26a10 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
26a20 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
26a30 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
26a40 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
26a50 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
26a60 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
26a70 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
26a80 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
26a90 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
26aa0 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
26ab0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
26ac0 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
26ad0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
26ae0 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
26af0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
26b00 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
26b10 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
26b20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
26b30 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
26b40 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
26b50 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
26b60 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
26b70 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
26b80 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
26b90 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
26ba0 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
26bb0 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
26bc0 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
26bd0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
26be0 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
26bf0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
26c00 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
26c10 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
26c20 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
26c30 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
26c40 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
26c50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
26c60 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
26c70 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
26c80 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
26c90 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
26ca0 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
26cb0 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
26cc0 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
26cd0 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
26ce0 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
26cf0 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
26d00 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
26d10 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
26d20 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
26d30 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
26d40 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
26d50 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
26d60 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
26d70 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
26d80 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
26d90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
26da0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
26db0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
26dc0 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
26dd0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
26de0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
26df0 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
26e00 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
26e10 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
26e20 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
26e30 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
26e40 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
26e50 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26e60 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
26e70 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
26e80 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
26e90 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
26ea0 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
26eb0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
26ec0 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
26ed0 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
26ee0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
26ef0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
26f00 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
26f10 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
26f20 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
26f30 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
26f40 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
26f50 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
26f60 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
26f70 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
26f80 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
26f90 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
26fa0 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
26fb0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
26fc0 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
26fd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26fe0 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
26ff0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
27000 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
27010 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
27020 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
27030 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
27040 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
27050 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
27060 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
27070 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
27080 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
27090 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
270a0 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
270b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
270c0 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
270d0 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
270e0 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
270f0 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
27100 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
27110 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
27120 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
27130 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
27140 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
27150 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
27160 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
27170 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
27180 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
27190 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
271a0 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
271b0 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
271c0 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
271d0 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
271e0 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
271f0 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
27200 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
27210 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
27220 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
27230 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
27240 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
27250 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
27260 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
27270 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
27280 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
27290 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
272a0 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
272b0 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
272c0 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
272d0 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
272e0 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
272f0 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
27300 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
27310 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
27320 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
27330 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
27340 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
27350 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
27360 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
27370 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
27380 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
27390 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
273a0 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
273b0 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
273c0 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
273d0 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
273e0 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
273f0 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
27400 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
27410 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
27420 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
27430 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
27440 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
27450 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
27460 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
27470 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
27480 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
27490 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
274a0 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
274b0 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
274c0 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
274d0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
274e0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
274f0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
27500 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
27510 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
27520 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
27530 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
27540 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
27550 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
27560 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
27570 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
27580 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
27590 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
275a0 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
275b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
275c0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
275d0 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
275e0 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
275f0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
27600 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
27610 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
27620 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
27630 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
27640 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
27650 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
27660 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
27670 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
27680 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
27690 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
276a0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
276b0 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
276c0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
276d0 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
276e0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
276f0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
27700 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
27710 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
27720 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
27730 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
27740 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
27750 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
27760 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
27770 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
27780 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
27790 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
277a0 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
277b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
277c0 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
277d0 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
277e0 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
277f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
27800 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
27810 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
27820 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
27830 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
27840 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
27850 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
27860 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
27870 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
27880 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
27890 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
278a0 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
278b0 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
278c0 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
278d0 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
278e0 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
278f0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
27900 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
27910 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
27920 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
27930 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
27940 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
27950 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
27960 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
27970 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
27980 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
27990 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
279a0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
279b0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
279c0 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
279d0 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
279e0 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
279f0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
27a00 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
27a10 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
27a20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
27a30 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
27a40 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
27a50 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
27a60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27a70 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
27a80 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
27a90 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
27aa0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27ab0 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
27ac0 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
27ad0 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
27ae0 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
27af0 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
27b00 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
27b10 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
27b20 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
27b30 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
27b40 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
27b50 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
27b60 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
27b70 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
27b80 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
27b90 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
27ba0 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
27bb0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
27bc0 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
27bd0 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
27be0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
27bf0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
27c00 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
27c10 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
27c20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
27c30 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
27c40 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
27c50 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
27c60 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
27c70 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
27c80 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
27c90 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
27ca0 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
27cb0 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
27cc0 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
27cd0 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
27ce0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
27cf0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
27d00 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
27d10 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
27d20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
27d30 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
27d40 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
27d50 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
27d60 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
27d70 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
27d80 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
27d90 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
27da0 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
27db0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
27dc0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
27dd0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
27de0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
27df0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
27e00 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
27e10 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
27e20 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
27e30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27e40 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
27e50 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
27e60 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
27e70 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
27e80 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
27e90 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
27ea0 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
27eb0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
27ec0 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
27ed0 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
27ee0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
27ef0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
27f00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
27f10 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
27f20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
27f30 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
27f40 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
27f50 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
27f60 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
27f70 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
27f80 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
27f90 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
27fa0 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
27fb0 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
27fc0 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
27fd0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
27fe0 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
27ff0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
28000 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
28010 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ry].*/.int sqlit
28020 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
28030 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
28040 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
28050 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
28060 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
28070 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
28080 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
28090 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
280a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
280b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
280c0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
280d0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
280e0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
280f0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
28100 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
28110 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
28120 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
28130 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
28140 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
28150 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
28160 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
28170 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
28180 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
28190 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
281a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
281b0 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
281c0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
281d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
281e0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
281f0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
28200 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
28210 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
28220 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
28230 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
28240 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
28250 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
28260 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
28270 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
28280 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
28290 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
282a0 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
282b0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
282c0 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
282d0 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
282e0 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
282f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
28300 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
28310 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
28320 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
28330 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
28340 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
28350 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
28360 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
28370 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
28380 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
28390 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
283a0 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
283b0 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
283c0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
283d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
283e0 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
283f0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
28400 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
28410 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
28420 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
28430 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
28440 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
28450 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
28460 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
28470 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
28480 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
28490 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
284a0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
284b0 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
284c0 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
284d0 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
284e0 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
284f0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
28500 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
28510 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
28520 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
28530 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
28540 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
28550 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
28560 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
28570 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
28580 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
28590 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
285a0 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
285b0 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
285c0 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
285d0 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
285e0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
285f0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
28600 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
28610 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
28620 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28630 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
28640 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
28650 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
28660 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
28670 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
28680 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
28690 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
286a0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
286b0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
286c0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
286d0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
286e0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
286f0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
28700 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
28710 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
28720 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
28730 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
28740 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
28750 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
28760 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
28770 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
28780 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
28790 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
287a0 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
287b0 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
287c0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
287d0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
287e0 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
287f0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
28800 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
28810 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
28820 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
28830 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
28840 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
28850 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
28860 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
28870 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
28880 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
28890 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
288a0 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
288b0 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
288c0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
288d0 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
288e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
288f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
28900 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
28910 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
28920 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
28930 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
28940 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
28950 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
28960 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
28970 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
28980 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
28990 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
289a0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
289b0 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
289c0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
289d0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
289e0 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
289f0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
28a00 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
28a10 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
28a20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
28a30 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
28a40 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
28a50 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
28a60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  );.int sqlite3_u
28a70 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
28a80 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
28a90 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
28aa0 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
28ab0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
28ac0 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
28ad0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
28ae0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
28af0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
28b00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
28b10 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
28b20 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  sages.** METHOD:
28b30 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
28b40 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
28b50 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  nt sqlite3_* API
28b60 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
28b70 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62   with .** [datab
28b80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
28b90 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74  D failed, then t
28ba0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
28bb0 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a  de(D) interface.
28bc0 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ** returns the n
28bd0 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
28be0 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
28bf0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
28c00 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63  or that.** API c
28c10 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d  all..** If the m
28c20 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
28c30 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66  all was successf
28c40 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ul,.** then the 
28c50 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
28c60 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  m sqlite3_errcod
28c70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
28c80 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
28c90 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
28ca0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
28cb0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
28cc0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
28cd0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
28ce0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
28cf0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
28d00 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
28d10 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
28d20 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
28d30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
28d40 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
28d50 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
28d60 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
28d70 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
28d80 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
28d90 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
28da0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
28db0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
28dc0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
28dd0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
28de0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
28df0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
28e00 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
28e10 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
28e20 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
28e30 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
28e40 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
28e50 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
28e60 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
28e70 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
28e80 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
28e90 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
28ea0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
28eb0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
28ec0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
28ed0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
28ee0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
28ef0 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
28f00 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
28f10 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
28f20 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
28f30 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
28f40 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
28f50 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
28f60 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
28f70 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
28f80 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
28f90 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
28fa0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
28fb0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
28fc0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
28fd0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
28fe0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
28ff0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
29000 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
29010 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
29020 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
29030 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
29040 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
29050 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
29060 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
29070 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
29080 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
29090 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
290a0 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
290b0 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
290c0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
290d0 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
290e0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
290f0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
29100 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
29110 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
29120 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
29130 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
29140 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
29150 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
29160 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
29170 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
29180 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
29190 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
291a0 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
291b0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
291c0 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
291d0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
291e0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
291f0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
29200 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
29210 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
29220 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
29230 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
29240 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
29250 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
29260 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
29270 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
29280 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
29290 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
292a0 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
292b0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
292c0 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
292d0 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20   be set..*/.int 
292e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
292f0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
29300 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
29310 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
29320 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
29330 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
29340 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
29350 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
29360 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
29370 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61  te3*);.const cha
29380 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
29390 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
293a0 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
293b0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
293c0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
293d0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
293e0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
293f0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
29400 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
29410 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
29420 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
29430 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
29440 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63  at.** has been c
29450 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e  ompiled into bin
29460 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20  ary form and is 
29470 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c  ready to be eval
29480 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  uated..**.** Thi
29490 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73  nk of each SQL s
294a0 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65  tatement as a se
294b0 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20  parate computer 
294c0 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a  program.  The.**
294d0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
294e0 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64  xt is source cod
294f0 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73  e.  A prepared s
29500 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
29510 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69  .** is the compi
29520 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e  led object code.
29530 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62    All SQL must b
29540 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  e converted into
29550 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73   a.** prepared s
29560 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20  tatement before 
29570 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a  it can be run..*
29580 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79  *.** The life-cy
29590 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  cle of a prepare
295a0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
295b0 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20  ct usually goes 
295c0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
295d0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
295e0 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65  eate the prepare
295f0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
29600 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
29610 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
29620 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
29630 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74  lues to [paramet
29640 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
29650 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
29660 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
29670 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
29680 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
29690 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
296a0 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
296b0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
296c0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
296d0 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
296e0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
296f0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
29700 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
29710 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
29720 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
29730 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
29740 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
29750 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
29760 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
29770 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
29780 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
29790 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
297a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
297b0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
297c0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
297d0 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  3.**.** ^(This i
297e0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
297f0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
29800 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
29810 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
29820 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
29830 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
29840 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
29850 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
29860 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
29870 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
29880 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
29890 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
298a0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
298b0 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
298c0 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
298d0 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
298e0 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
298f0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
29900 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
29910 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
29920 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
29930 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
29940 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
29950 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
29960 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
29970 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
29980 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
29990 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
299a0 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
299b0 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
299c0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
299d0 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
299e0 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
299f0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
29a00 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
29a10 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
29a20 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
29a30 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
29a40 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
29a50 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
29a60 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
29a70 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
29a80 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
29a90 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
29aa0 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
29ab0 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
29ac0 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
29ad0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
29ae0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
29af0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
29b00 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
29b10 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
29b20 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
29b30 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
29b40 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
29b50 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
29b60 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
29b70 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
29b80 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
29b90 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
29ba0 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
29bb0 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
29bc0 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
29bd0 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
29be0 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
29bf0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29c00 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
29c10 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
29c20 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
29c30 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
29c40 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
29c50 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
29c60 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
29c70 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
29c80 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
29c90 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
29ca0 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
29cb0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
29cc0 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
29cd0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
29ce0 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
29cf0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
29d00 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
29d10 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
29d20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
29d30 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
29d40 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
29d50 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
29d60 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
29d70 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
29d80 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
29d90 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
29da0 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
29db0 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
29dc0 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
29dd0 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
29de0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
29df0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
29e00 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
29e10 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
29e20 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
29e30 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
29e40 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
29e50 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
29e60 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
29e70 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
29e80 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
29e90 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
29ea0 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
29eb0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
29ec0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
29ed0 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
29ee0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
29ef0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
29f00 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
29f10 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
29f20 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
29f30 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
29f40 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
29f50 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
29f60 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
29f70 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
29f80 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
29f90 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
29fa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29fb0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
29fc0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
29fd0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
29fe0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
29ff0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
2a000 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2a010 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
2a020 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
2a030 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
2a040 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
2a050 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
2a060 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
2a070 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
2a080 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
2a090 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
2a0a0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
2a0b0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
2a0c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2a0d0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
2a0e0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
2a0f0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
2a100 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
2a110 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2a120 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2a130 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
2a140 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2a150 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
2a160 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
2a170 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
2a180 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
2a190 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a1a0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
2a1b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a1c0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
2a1d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a1e0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2a1f0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2a200 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
2a210 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2a220 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
2a230 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a240 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
2a250 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a260 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
2a270 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
2a280 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
2a290 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
2a2a0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2a2b0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
2a2c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2a2d0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
2a2e0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
2a2f0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
2a300 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
2a310 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a320 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
2a330 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a340 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
2a350 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a360 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
2a370 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
2a380 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
2a390 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2a3a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
2a3b0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
2a3c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a3d0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2a3e0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
2a3f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2a400 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
2a410 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
2a420 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
2a430 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2a440 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
2a450 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a460 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
2a470 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a480 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
2a490 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
2a4a0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
2a4b0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
2a4c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
2a4d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
2a4e0 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  If [sqlite3_prep
2a4f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
2a500 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74  the equivalent t
2a510 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65  ries to allocate
2a520 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20   space for more 
2a530 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f  than this many o
2a540 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73  pcodes.** in a s
2a550 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73  ingle prepared s
2a560 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c  tatement, an SQL
2a570 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20  ITE_NOMEM error 
2a580 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
2a590 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2a5a0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2a5b0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
2a5c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2a5d0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
2a5e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a5f0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2a600 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
2a610 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
2a620 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
2a630 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
2a640 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2a650 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
2a660 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2a670 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
2a680 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
2a690 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
2a6a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a6b0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2a6c0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
2a6d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
2a6e0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2a6f0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2a700 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
2a710 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
2a720 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2a730 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
2a740 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
2a750 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2a760 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2a770 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
2a780 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a790 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2a7a0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
2a7b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
2a7c0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
2a7d0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
2a7e0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
2a7f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a800 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2a810 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
2a820 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2a830 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
2a840 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a850 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
2a860 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
2a870 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2a880 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  [SQLITE_LIMIT_WO
2a890 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e  RKER_THREADS]] ^
2a8a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a8b0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2a8c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a8d0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2a8e0 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72  of auxiliary wor
2a8f0 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74  ker threads that
2a900 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72   a single.** [pr
2a910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a920 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64  ] may start.</dd
2a930 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
2a940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a950 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
2a960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
2a970 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a980 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2a990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a9a0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2a9b0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
2a9c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a9d0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2a9e0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2a9f0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2aa00 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
2aa10 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2aa20 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
2aa30 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2aa40 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2aa50 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
2aa60 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
2aa70 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2aa80 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
2aa90 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
2aaa0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
2aab0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
2aac0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
2aad0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2aae0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2aaf0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
2ab00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
2ab10 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
2ab20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
2ab30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
2ab40 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
2ab50 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
2ab60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2ab70 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20  WORKER_THREADS  
2ab80 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a           11../*.
2ab90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
2aba0 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  pare Flags.**.**
2abb0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2abc0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
2abd0 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20 62  flags that can b
2abe0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  e passed into.**
2abf0 20 22 70 72 65 70 46 6c 61 67 73 22 20 70 61 72   "prepFlags" par
2ac00 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73  ameter of the [s
2ac10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ac20 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  3()] and.** [sql
2ac30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2ac40 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e  3()] interfaces.
2ac50 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73  .**.** New flags
2ac60 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
2ac70 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2ac80 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
2ac90 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
2aca0 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2acb0 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  STENT]] ^(<dt>SQ
2acc0 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2acd0 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20  SISTENT</dt>.** 
2ace0 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50  <dd>The SQLITE_P
2acf0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2ad00 54 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74  T flag is a hint
2ad10 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c   to the query pl
2ad20 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  anner.** that th
2ad30 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2ad40 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74  ment will be ret
2ad50 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67  ained for a long
2ad60 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f   time and.** pro
2ad70 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e  bably reused man
2ad80 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68  y times.)^ ^With
2ad90 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b  out this flag, [
2ada0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2adb0 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  v3()].** and [sq
2adc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2add0 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61  v3()] assume tha
2ade0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2adf0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a  tatement will .*
2ae00 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f  * be used just o
2ae10 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61  nce or at most a
2ae20 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74   few times and t
2ae30 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73  hen destroyed us
2ae40 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2ae50 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61  finalize()] rela
2ae60 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65  tively soon. The
2ae70 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
2ae80 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20  ntation acts.** 
2ae90 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79 20  on this hint by 
2aea0 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65  avoiding the use
2aeb0 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d   of [lookaside m
2aec0 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74  emory] so as not
2aed0 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74   to.** deplete t
2aee0 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65  he limited store
2aef0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
2af00 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65 72  mory. Future ver
2af10 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69  sions of.** SQLi
2af20 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68  te may act on th
2af30 69 73 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e  is hint differen
2af40 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  tly..** </dl>.*/
2af50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2af60 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2af70 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
2af80 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x01../*.** CAPI
2af90 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
2afa0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2afb0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2afc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2afd0 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
2afe0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
2aff0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2b000 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
2b010 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73  execute an SQL s
2b020 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73  tatement, it mus
2b030 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
2b040 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
2b050 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
2b060 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
2b070 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72  se routines.  Or
2b080 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  , in other words
2b090 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  , these routines
2b0a0 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63  .** are construc
2b0b0 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72  tors for the [pr
2b0c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b0d0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
2b0e0 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f  The preferred ro
2b0f0 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20  utine to use is 
2b100 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b110 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20  _v2()].  The.** 
2b120 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b130 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73  ()] interface is
2b140 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75   legacy and shou
2b150 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
2b160 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2b170 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20  re_v3()] has an 
2b180 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73  extra "prepFlags
2b190 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73  " option that is
2b1a0 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65   used.** for spe
2b1b0 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a  cial purposes..*
2b1c0 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20  *.** The use of 
2b1d0 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66  the UTF-8 interf
2b1e0 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65  aces is preferre
2b1f0 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72  d, as SQLite cur
2b200 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61  rently.** does a
2b210 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67  ll parsing using
2b220 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46   UTF-8.  The UTF
2b230 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61  -16 interfaces a
2b240 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61  re provided.** a
2b250 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e  s a convenience.
2b260 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74    The UTF-16 int
2b270 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20  erfaces work by 
2b280 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a  converting the.*
2b290 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74  * input text int
2b2a0 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e  o UTF-8, then in
2b2b0 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65  voking the corre
2b2c0 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69  sponding UTF-8 i
2b2d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2b2e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2b2f0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
2b300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b310 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
2b320 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
2b330 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2b340 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2b350 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2b360 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
2b370 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2b380 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
2b390 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2b3a0 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
2b3b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
2b3c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
2b3d0 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
2b3e0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2b3f0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
2b400 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
2b410 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
2b420 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2b430 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  are(), sqlite3_p
2b440 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20  repare_v2(),.** 
2b450 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2b460 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65  are_v3().** inte
2b470 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
2b480 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
2b490 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74  epare16(), sqlit
2b4a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2b4b0 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2b4c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2b4d0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
2b4e0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
2b4f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67   argument is neg
2b500 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c  ative, then zSql
2b510 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
2b520 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
2b530 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
2b540 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69   nByte is positi
2b550 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
2b560 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2b570 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
2b580 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65  zSql.  ^If nByte
2b590 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e   is zero, then n
2b5a0 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  o prepared.** st
2b5b0 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72  atement is gener
2b5c0 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ated..** If the 
2b5d0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61  caller knows tha
2b5e0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
2b5f0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
2b600 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a  minated, then.**
2b610 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
2b620 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  l performance ad
2b630 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69  vantage to passi
2b640 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
2b650 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
2b660 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2b670 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
2b680 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
2b690 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
2b6a0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e   nul-terminator.
2b6b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
2b6c0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
2b6d0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
2b6e0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
2b6f0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
2b700 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
2b710 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
2b720 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2b730 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2b740 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
2b750 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
2b760 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
2b770 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
2b780 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
2b790 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
2b7a0 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
2b7b0 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
2b7c0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
2b7d0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
2b7e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2b7f0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
2b800 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
2b810 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
2b820 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
2b830 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
2b840 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
2b850 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
2b860 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
2b870 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
2b880 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
2b890 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
2b8a0 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
2b8b0 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
2b8c0 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
2b8d0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
2b8e0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
2b8f0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
2b900 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
2b910 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2b920 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b930 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
2b940 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
2b950 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
2b960 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
2b970 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
2b980 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2b990 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
2b9a0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2b9b0 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
2b9c0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
2b9d0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2b9e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
2b9f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ba00 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  2(), sqlite3_pre
2ba10 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74  pare_v3(), sqlit
2ba20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2ba30 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2ba40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2ba50 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2ba60 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
2ba70 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
2ba80 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69  ..** The older i
2ba90 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74  nterfaces (sqlit
2baa0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
2bab0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2bac0 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74  16()).** are ret
2bad0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
2bae0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2baf0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
2bb00 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
2bb10 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22  .** ^In the "vX"
2bb20 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2bb30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2bb40 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
2bb50 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
2bb60 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2bb70 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
2bb80 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
2bb90 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
2bba0 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
2bbb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2bbc0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
2bbd0 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
2bbe0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
2bbf0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
2bc00 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2bc10 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2bc20 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
2bc30 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
2bc40 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
2bc50 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
2bc60 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
2bc70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2bc80 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2bc90 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
2bca0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
2bcb0 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
2bcc0 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
2bcd0 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
2bce0 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
2bcf0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
2bd00 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
2bd10 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
2bd20 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
2bd30 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
2bd40 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2bd50 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
2bd60 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
2bd70 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
2bd80 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
2bd90 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
2bda0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
2bdb0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
2bdc0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
2bdd0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
2bde0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
2bdf0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
2be00 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
2be10 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
2be20 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
2be30 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
2be40 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
2be50 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
2be60 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2be70 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
2be80 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
2be90 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
2bea0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
2beb0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
2bec0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
2bed0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
2bee0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
2bef0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
2bf00 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
2bf10 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
2bf20 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2bf30 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
2bf40 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
2bf50 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
2bf60 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2bf70 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2bf80 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2bf90 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
2bfa0 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
2bfb0 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
2bfc0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
2bfd0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
2bfe0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2bff0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
2c000 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
2c010 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
2c020 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
2c030 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2c040 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
2c050 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
2c060 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
2c070 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
2c080 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
2c090 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
2c0a0 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
2c0b0 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
2c0c0 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
2c0d0 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
2c0e0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2c0f0 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
2c100 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
2c110 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
2c120 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
2c130 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
2c140 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2c150 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
2c160 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
2c170 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
2c180 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
2c190 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
2c1a0 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
2c1b0 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ed..** </li>.**.
2c1c0 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70  ** <p>^sqlite3_p
2c1d0 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66 66  repare_v3() diff
2c1e0 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ers from sqlite3
2c1f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e  _prepare_v2() on
2c200 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20  ly in having.** 
2c210 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46 6c  the extra prepFl
2c220 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77  ags parameter, w
2c230 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61 72  hich is a bit ar
2c240 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f  ray consisting o
2c250 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  f zero or.** mor
2c260 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
2c270 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2c280 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41  ENT|SQLITE_PREPA
2c290 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54  RE_*] flags.  ^T
2c2a0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
2c2b0 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72  epare_v2() inter
2c2c0 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74  face works exact
2c2d0 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ly the same as.*
2c2e0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
2c2f0 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a 65  e_v3() with a ze
2c300 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61 72  ro prepFlags par
2c310 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ameter..** </ol>
2c320 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c330 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
2c340 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2c350 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2c360 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c370 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2c380 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2c390 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2c3a0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2c3b0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2c3c0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2c3d0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2c3e0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2c3f0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2c400 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2c410 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2c420 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2c430 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2c440 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2c450 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2c460 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2c470 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
2c480 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2c490 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2c4a0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2c4b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2c4c0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2c4d0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2c4e0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2c4f0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2c500 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2c510 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2c520 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2c530 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c540 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c550 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2c560 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c570 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2c580 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2c590 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2c5a0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2c5b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c5c0 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2c5d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2c5e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2c5f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2c600 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2c610 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2c620 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2c630 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2c640 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2c650 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2c660 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2c670 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e  */.  unsigned in
2c680 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20  t prepFlags, /* 
2c690 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c  Zero or more SQL
2c6a0 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61  ITE_PREPARE_ fla
2c6b0 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  gs */.  sqlite3_
2c6c0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2c6d0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2c6e0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2c6f0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2c700 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2c710 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2c720 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2c730 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2c740 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2c750 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2c760 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2c770 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2c780 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2c790 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2c7a0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2c7b0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2c7c0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2c7d0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2c7e0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2c7f0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2c800 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2c810 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2c820 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2c830 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2c840 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2c850 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2c860 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2c870 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2c880 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c890 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
2c8a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2c8b0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2c8c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2c8d0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2c8e0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2c8f0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2c900 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2c910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2c920 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2c930 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2c940 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2c950 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2c960 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2c970 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c980 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2c990 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2c9a0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2c9b0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2c9c0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2c9d0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20  _prepare16_v3(. 
2c9e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2c9f0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2ca00 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2ca10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2ca20 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2ca30 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2ca40 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2ca50 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2ca60 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2ca70 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2ca80 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2ca90 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65  unsigned int pre
2caa0 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20  pFlags, /* Zero 
2cab0 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50  or more SQLITE_P
2cac0 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f  REPARE_ flags */
2cad0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2cae0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2caf0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2cb00 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2cb10 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2cb20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2cb30 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2cb40 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2cb50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cb60 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
2cb70 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
2cb80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2cb90 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2cba0 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74  lite3_sql(P) int
2cbb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2cbc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
2cbd0 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a  py of the UTF-8.
2cbe0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
2cbf0 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70   to create [prep
2cc00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cc10 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72  P if P was.** cr
2cc20 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
2cc30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2cc40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2cc50 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v3()],.** [sql
2cc60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2cc70 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  2()], or [sqlite
2cc80 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2cc90 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
2cca0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2ccb0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2ccc0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2ccd0 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2cce0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2ccf0 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70  he SQL text of p
2cd00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cd10 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75  t P with.** [bou
2cd20 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65  nd parameters] e
2cd30 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  xpanded..**.** ^
2cd40 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2cd50 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2cd60 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64  ement is created
2cd70 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a   using the SQL.*
2cd80 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24  * text "SELECT $
2cd90 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66  abc,:xyz" and if
2cda0 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20   parameter $abc 
2cdb0 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65  is bound to inte
2cdc0 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20  ger 2345.** and 
2cdd0 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69  parameter :xyz i
2cde0 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20  s unbound, then 
2cdf0 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69  sqlite3_sql() wi
2ce00 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  ll return.** the
2ce10 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67   original string
2ce20 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  , "SELECT $abc,:
2ce30 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33  xyz" but sqlite3
2ce40 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a  _expanded_sql().
2ce50 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22  ** will return "
2ce60 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c  SELECT 2345,NULL
2ce70 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ".)^.**.** ^The 
2ce80 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2ce90 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65  _sql() interface
2cea0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
2ceb0 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
2cec0 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c  mory.** is avail
2ced0 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65  able to hold the
2cee0 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74   result, or if t
2cef0 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20  he result would 
2cf00 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68  exceed the.** th
2cf10 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67  e maximum string
2cf20 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e   length determin
2cf30 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ed by the [SQLIT
2cf40 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e  E_LIMIT_LENGTH].
2cf50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
2cf60 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
2cf70 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
2cf80 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73  me option limits
2cf90 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
2cfa0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
2cfb0 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68  expansions.  ^Th
2cfc0 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54  e [SQLITE_OMIT_T
2cfd0 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
2cfe0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75  me.** option cau
2cff0 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61  ses sqlite3_expa
2d000 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c  nded_sql() to al
2d010 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ways return NULL
2d020 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72  ..**.** ^The str
2d030 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
2d040 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69  sqlite3_sql(P) i
2d050 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c  s managed by SQL
2d060 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75  ite and is.** au
2d070 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
2d080 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61  d when the prepa
2d090 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
2d0a0 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e   finalized..** ^
2d0b0 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2d0c0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65  ned by sqlite3_e
2d0d0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20  xpanded_sql(P), 
2d0e0 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e  on the other han
2d0f0 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65  d,.** is obtaine
2d100 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2d110 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75  malloc()] and mu
2d120 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68  st be free by th
2d130 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
2d140 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74   by passing it t
2d150 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
2d160 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
2d170 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
2d180 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2d190 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  mt);.char *sqlit
2d1a0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2d1b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2d1c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2d1d0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2d1e0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2d1f0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2d200 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
2d210 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2d220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d230 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2d240 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
2d250 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2d260 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
2d270 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
2d280 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d290 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
2d2a0 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
2d2b0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
2d2c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2d2d0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
2d2e0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
2d2f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2d300 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
2d310 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
2d320 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
2d330 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
2d340 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
2d350 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
2d360 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
2d370 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2d380 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
2d390 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
2d3a0 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
2d3b0 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
2d3c0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
2d3d0 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
2d3e0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
2d3f0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
2d400 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
2d410 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2d420 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
2d430 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
2d440 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
2d450 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
2d460 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2d470 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
2d480 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2d490 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2d4a0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2d4b0 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
2d4c0 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
2d4d0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
2d4e0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
2d4f0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
2d500 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
2d510 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
2d520 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
2d530 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
2d540 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
2d550 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
2d560 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
2d570 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d580 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2d590 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
2d5a0 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
2d5b0 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
2d5c0 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
2d5d0 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
2d5e0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
2d5f0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
2d600 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
2d610 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
2d620 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
2d630 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
2d640 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
2d650 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
2d660 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
2d670 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2d680 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
2d690 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
2d6a0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
2d6b0 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
2d6c0 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
2d6d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
2d6e0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
2d6f0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
2d700 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2d710 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2d720 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e  es on disk..** ^
2d730 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2d740 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65  _readonly() inte
2d750 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2d760 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73  ue for [BEGIN] s
2d770 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20  ince.** [BEGIN] 
2d780 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65  merely sets inte
2d790 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20  rnal flags, but 
2d7a0 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  the [BEGIN|BEGIN
2d7b0 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a   IMMEDIATE] and.
2d7c0 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  ** [BEGIN|BEGIN 
2d7d0 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61  EXCLUSIVE] comma
2d7e0 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65  nds do touch the
2d7f0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f   database and so
2d800 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2d810 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75  _readonly() retu
2d820 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68  rns false for th
2d830 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f  ose commands..*/
2d840 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2d850 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
2d860 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2d870 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d880 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2d890 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2d8a0 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
2d8b0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2d8c0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2d8d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2d8e0 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2d8f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2d900 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2d910 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2d920 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2d930 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2d940 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2d950 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2d960 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2d970 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
2d980 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
2d990 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2d9a0 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
2d9b0 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
2d9c0 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
2d9d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2d9e0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2d9f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2da00 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2da10 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2da20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2da30 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2da40 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2da50 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2da60 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2da70 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2da80 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2da90 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2daa0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2dab0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2dac0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2dad0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2dae0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2daf0 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2db00 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2db10 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2db20 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2db30 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2db40 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2db50 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2db60 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2db70 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2db80 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2db90 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2dba0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2dbb0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2dbc0 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2dbd0 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2dbe0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2dbf0 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2dc00 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
2dc10 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2dc20 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2dc30 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2dc40 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2dc50 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2dc60 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2dc70 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2dc80 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2dc90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2dca0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2dcb0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2dcc0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2dcd0 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2dce0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2dcf0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2dd00 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2dd10 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2dd20 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2dd30 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2dd40 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2dd50 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2dd60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2dd70 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2dd80 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2dd90 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2dda0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2ddb0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2ddc0 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2ddd0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2dde0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2ddf0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2de00 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2de10 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2de20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2de30 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2de40 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2de50 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2de60 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2de70 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2de80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2de90 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2dea0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2deb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2dec0 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2ded0 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2dee0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2def0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2df00 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2df10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2df20 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2df30 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2df40 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2df50 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2df60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2df70 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2df80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2df90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2dfa0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2dfb0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2dfc0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2dfd0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2dfe0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2dff0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2e000 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2e010 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e020 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2e030 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2e040 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2e050 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e060 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2e070 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2e080 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2e090 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2e0a0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2e0b0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2e0c0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2e0d0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2e0e0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2e0f0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2e100 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2e110 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2e120 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2e130 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2e140 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2e150 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2e160 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2e170 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2e180 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2e190 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2e1a0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2e1b0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2e1c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2e1d0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2e1e0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2e1f0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2e200 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2e210 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2e220 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2e230 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2e240 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2e250 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2e260 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2e270 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e280 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2e290 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2e2a0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2e2b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e2c0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2e2d0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2e2e0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2e2f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e300 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2e310 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2e320 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2e330 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2e340 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e350 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2e360 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e370 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2e380 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2e390 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e3a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2e3b0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2e3c0 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a   as arguments.**
2e3d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2e3e0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73  ult_value()], [s
2e3f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2e400 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2e410 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2e420 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
2e430 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
2e440 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2e450 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
2e460 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
2e470 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
2e480 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e490 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
2e4a0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2e4b0 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
2e4c0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2e4d0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2e4e0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2e4f0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2e500 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2e510 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2e520 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2e530 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2e540 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2e550 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2e560 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2e570 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2e580 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2e590 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2e5a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e5b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2e5c0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2e5d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2e5e0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e5f0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2e600 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2e610 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2e620 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2e630 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2e640 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2e650 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2e660 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2e670 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2e680 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2e690 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2e6a0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2e6b0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2e6c0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2e6d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2e6e0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2e6f0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2e700 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2e710 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2e720 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2e730 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2e740 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2e750 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2e760 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2e770 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2e780 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2e790 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2e7a0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2e7b0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2e7c0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2e7d0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2e7e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e7f0 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2e800 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2e810 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2e820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2e830 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2e840 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2e850 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2e860 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2e870 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2e880 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2e890 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2e8a0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2e8b0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2e8c0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2e8d0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2e8e0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2e8f0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2e900 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2e910 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2e920 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2e930 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2e940 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2e950 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2e960 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2e970 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2e980 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2e990 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2e9a0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2e9b0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2e9c0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2e9d0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2e9e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2e9f0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2ea00 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2ea10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2ea20 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2ea30 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2ea40 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2ea50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2ea60 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2ea70 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2ea80 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2ea90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2eaa0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2eab0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2eac0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2ead0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2eae0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2eaf0 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2eb00 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2eb10 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2eb20 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2eb30 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2eb40 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2eb50 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2eb60 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2eb70 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2eb80 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2eb90 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2eba0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2ebb0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2ebc0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2ebd0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2ebe0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2ebf0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2ec00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ec10 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2ec20 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2ec30 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2ec40 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2ec50 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2ec60 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2ec70 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2ec80 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2ec90 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2eca0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2ecb0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2ecc0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2ecd0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2ece0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2ecf0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2ed00 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2ed10 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2ed20 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2ed30 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2ed40 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2ed50 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2ed60 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2ed70 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2ed80 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2ed90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2eda0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2edb0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2edc0 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2edd0 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2ede0 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2edf0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2ee00 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2ee10 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2ee20 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2ee30 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2ee40 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2ee50 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2ee60 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2ee70 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2ee80 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2ee90 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2eea0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2eeb0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2eec0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2eed0 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2eee0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2eef0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2ef00 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2ef10 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2ef20 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2ef30 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2ef40 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2ef50 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2ef60 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2ef70 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2ef80 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2ef90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2efa0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2efb0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2efc0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2efd0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2efe0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2eff0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2f000 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2f010 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2f020 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2f030 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2f040 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
2f050 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f060 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
2f070 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
2f080 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
2f090 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
2f0a0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
2f0b0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
2f0c0 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
2f0d0 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
2f0e0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
2f0f0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
2f100 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
2f110 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
2f120 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
2f130 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2f140 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
2f150 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
2f160 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
2f170 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
2f180 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
2f190 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
2f1a0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
2f1b0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
2f1c0 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
2f1d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2f1e0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2f1f0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
2f200 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
2f210 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2f220 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2f230 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2f240 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2f250 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2f260 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2f270 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2f280 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2f290 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2f2a0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2f2b0 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2f2c0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
2f2d0 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
2f2e0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2f2f0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2f300 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2f310 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2f320 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2f330 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2f340 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2f350 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2f360 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2f370 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2f380 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2f390 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2f3a0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2f3b0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2f3c0 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2f3d0 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2f3e0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2f3f0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2f400 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2f410 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2f420 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2f430 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2f440 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2f450 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2f460 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
2f470 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
2f480 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2f490 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
2f4a0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2f4b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2f4c0 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
2f4d0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2f4e0 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
2f4f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2f500 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
2f510 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2f520 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2f530 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
2f540 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
2f550 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
2f560 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
2f570 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
2f580 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
2f590 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
2f5a0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2f5b0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
2f5c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2f5d0 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
2f5e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2f5f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2f600 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2f610 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2f620 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2f630 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2f640 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2f650 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2f660 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2f670 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2f680 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2f690 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2f6a0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2f6b0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2f6c0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2f6d0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2f6e0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2f6f0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2f700 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2f710 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2f720 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2f730 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2f740 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2f750 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2f760 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2f770 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2f780 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2f790 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   BLOB..**.** ^Th
2f7a0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2f7b0 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44  ointer(S,I,P,T,D
2f7c0 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73  ) routine causes
2f7d0 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65   the I-th parame
2f7e0 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61  ter in.** [prepa
2f7f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2f800 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20   to have an SQL 
2f810 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62  value of NULL, b
2f820 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a  ut to also be.**
2f830 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2f840 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f   the pointer P o
2f850 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73  f type T.  ^D is
2f860 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
2f870 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70  ointer or.** a p
2f880 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
2f890 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
2f8a0 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77  for P. ^SQLite w
2f8b0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a  ill invoke the.*
2f8c0 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  * destructor D w
2f8d0 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
2f8e0 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20  ument of P when 
2f8f0 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 75  it is finished u
2f900 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20  sing.** P.  The 
2f910 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  T parameter shou
2f920 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20 73  ld be a static s
2f930 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c  tring, preferabl
2f940 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69  y a string.** li
2f950 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74  teral. The sqlit
2f960 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
2f970 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72  ) routine is par
2f980 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69  t of the.** [poi
2f990 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74  nter passing int
2f9a0 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f  erface] added fo
2f9b0 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e  r SQLite 3.20.0.
2f9c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2f9d0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2f9e0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2f9f0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2fa00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2fa10 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2fa20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2fa30 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2fa40 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2fa50 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2fa60 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2fa70 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2fa80 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2fa90 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2faa0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2fab0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2fac0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2fad0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2fae0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2faf0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2fb00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fb10 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2fb20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2fb30 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2fb40 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2fb50 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2fb60 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2fb70 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2fb80 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2fb90 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2fba0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2fbb0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2fbc0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2fbd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fbe0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2fbf0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2fc00 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2fc10 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2fc20 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2fc30 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2fc40 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2fc50 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2fc60 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2fc70 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2fc80 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2fc90 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2fca0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2fcb0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2fcc0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2fcd0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2fce0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2fcf0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2fd00 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2fd10 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2fd20 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2fd30 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2fd40 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2fd50 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2fd60 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2fd70 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2fd80 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2fd90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2fda0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2fdb0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2fdc0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2fdd0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2fde0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2fdf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fe00 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2fe10 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2fe20 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2fe30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2fe40 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2fe50 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2fe60 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2fe70 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2fe80 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2fe90 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2fea0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
2feb0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2fec0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
2fed0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2fee0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
2fef0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
2ff00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2ff10 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2ff20 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2ff30 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
2ff40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2ff50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ff60 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2ff70 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2ff80 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
2ff90 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
2ffa0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2ffb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2ffc0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2ffd0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2ffe0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2fff0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
30000 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
30010 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
30020 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
30030 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
30040 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
30050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30060 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
30070 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
30080 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
30090 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
300a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
300b0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
300c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
300d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
300e0 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ter(sqlite3_stmt
300f0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63  *, int, void*, c
30100 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 28  onst char*,void(
30110 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
30120 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
30130 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
30140 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
30150 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
30160 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  nd_zeroblob64(sq
30170 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30180 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
30190 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
301a0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
301b0 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
301c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
301d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
301e0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
301f0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
30200 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
30210 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
30220 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
30230 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
30240 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
30250 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
30260 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
30270 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
30280 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
30290 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
302a0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
302b0 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
302c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
302d0 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
302e0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
302f0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
30300 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
30310 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
30320 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
30330 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
30340 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
30350 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
30360 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
30370 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
30380 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
30390 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
303a0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
303b0 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
303c0 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
303d0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
303e0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
303f0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
30400 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
30410 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
30420 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
30430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30440 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
30450 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
30460 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30470 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
30480 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30490 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
304a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
304b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
304c0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
304d0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
304e0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
304f0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
30500 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30510 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
30520 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30530 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
30540 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
30550 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
30560 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30570 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
30580 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
30590 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
305a0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
305b0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
305c0 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
305d0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
305e0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
305f0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
30600 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
30610 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
30620 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
30630 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
30640 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
30650 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
30660 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
30670 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
30680 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
30690 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
306a0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
306b0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
306c0 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
306d0 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
306e0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
306f0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
30700 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
30710 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
30720 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
30730 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
30740 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
30750 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
30760 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
30770 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
30780 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
30790 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
307a0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
307b0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
307c0 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
307d0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
307e0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
307f0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
30800 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
30810 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
30820 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a  prepare16()],.**
30830 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30840 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73  e16_v2()], or [s
30850 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30860 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v3()]..**.** Se
30870 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
30880 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
30890 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
308a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
308b0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
308c0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
308d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
308e0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
308f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
30900 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30910 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
30920 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
30930 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
30940 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
30950 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
30960 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
30970 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30980 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
30990 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
309a0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
309b0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
309c0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
309d0 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
309e0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
309f0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
30a00 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
30a10 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
30a20 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
30a30 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
30a40 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
30a50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
30a60 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
30a70 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
30a80 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
30a90 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
30aa0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
30ab0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
30ac0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
30ad0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
30ae0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
30af0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
30b00 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
30b10 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
30b20 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
30b30 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
30b40 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
30b50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30b60 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
30b70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30b80 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
30b90 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
30ba0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30bb0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
30bc0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
30bd0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
30be0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
30bf0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
30c00 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
30c10 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
30c20 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30c30 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
30c40 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
30c50 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
30c60 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
30c70 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
30c80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
30c90 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
30ca0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
30cb0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
30cc0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
30cd0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
30ce0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
30cf0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
30d00 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
30d10 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
30d20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
30d30 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
30d40 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
30d50 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
30d60 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30d70 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
30d80 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
30d90 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
30da0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
30db0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
30dc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49  d statement]. ^I
30dd0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
30de0 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d  eturns 0, that m
30df0 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72  eans the .** [pr
30e00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30e10 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74  ] returns no dat
30e20 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
30e30 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20  n [UPDATE])..** 
30e40 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62  ^However, just b
30e50 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74  ecause this rout
30e60 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
30e70 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f  sitive number do
30e80 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74  es not.** mean t
30e90 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  hat one or more 
30ea0 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c  rows of data wil
30eb0 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  l be returned.  
30ec0 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  ^A SELECT statem
30ed0 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  ent.** will alwa
30ee0 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69  ys have a positi
30ef0 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ve sqlite3_colum
30f00 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65  n_count() but de
30f10 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a  pending on the.*
30f20 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  * WHERE clause c
30f30 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
30f40 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74  he table content
30f50 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72  , it might retur
30f60 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a  n no rows..**.**
30f70 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
30f80 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
30f90 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
30fa0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
30fb0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
30fc0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
30fd0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
30fe0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
30ff0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31000 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31010 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
31020 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
31030 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
31040 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
31050 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
31060 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
31070 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
31080 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
31090 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
310a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
310b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
310c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
310d0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
310e0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
310f0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
31100 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
31110 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
31120 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
31130 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
31140 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
31150 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31160 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
31170 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
31180 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
31190 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
311a0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
311b0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
311c0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
311d0 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
311e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
311f0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
31200 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
31210 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
31220 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31230 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
31240 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
31250 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
31260 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
31270 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
31280 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
31290 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
312a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
312b0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
312c0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
312d0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
312e0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
312f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
31300 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
31310 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
31320 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
31330 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
31340 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
31350 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
31360 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
31370 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
31380 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
31390 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
313a0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
313b0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
313c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
313d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
313e0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
313f0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
31400 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
31410 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
31420 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
31430 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
31440 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
31450 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
31460 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
31470 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
31480 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
31490 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
314a0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
314b0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
314c0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
314d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
314e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
314f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31500 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
31510 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31520 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
31530 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
31540 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31550 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
31560 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
31570 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31580 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31590 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
315a0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
315b0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
315c0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
315d0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
315e0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
315f0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
31600 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
31610 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
31620 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
31630 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
31640 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
31650 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
31660 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
31670 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
31680 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
31690 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
316a0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
316b0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
316c0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
316d0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
316e0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
316f0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
31700 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
31710 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
31720 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
31730 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
31740 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
31750 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
31760 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
31770 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
31780 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
31790 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
317a0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
317b0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
317c0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
317d0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
317e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
317f0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
31800 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
31810 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
31820 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
31830 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
31840 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
31850 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
31860 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
31870 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
31880 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
31890 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
318a0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
318b0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
318c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
318d0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
318e0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
318f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31900 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
31910 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
31920 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
31930 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
31940 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
31950 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
31960 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
31970 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
31980 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
31990 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
319a0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
319b0 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
319c0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
319d0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
319e0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
319f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
31a00 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
31a10 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
31a20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
31a30 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
31a40 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
31a50 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
31a60 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
31a70 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
31a80 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
31a90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31aa0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
31ab0 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
31ac0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
31ad0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
31ae0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
31af0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
31b00 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
31b10 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
31b20 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
31b30 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
31b40 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
31b50 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
31b60 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
31b70 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
31b80 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
31b90 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
31ba0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
31bb0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
31bc0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
31bd0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
31be0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
31bf0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
31c00 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
31c10 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
31c20 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
31c30 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
31c40 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
31c50 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
31c60 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
31c70 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
31c80 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
31c90 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
31ca0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
31cb0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
31cc0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
31cd0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
31ce0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
31cf0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
31d00 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
31d10 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
31d20 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
31d30 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
31d40 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
31d50 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
31d60 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
31d70 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
31d80 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
31d90 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
31da0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
31db0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
31dc0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
31dd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
31de0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
31df0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
31e00 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
31e10 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
31e20 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
31e30 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
31e40 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
31e50 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
31e60 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
31e70 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
31e80 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
31e90 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
31ea0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
31eb0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
31ec0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
31ed0 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
31ee0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
31ef0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
31f00 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
31f10 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
31f20 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
31f30 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
31f40 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
31f50 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
31f60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
31f70 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
31f80 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31f90 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
31fa0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
31fb0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
31fc0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
31fd0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
31fe0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
31ff0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
32000 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
32010 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
32020 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
32030 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
32040 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
32050 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
32060 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
32070 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
32080 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
32090 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
320a0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
320b0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
320c0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
320d0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
320e0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
320f0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
32100 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
32110 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
32120 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
32130 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
32140 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
32150 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
32160 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
32170 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
32180 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
32190 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
321a0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
321b0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
321c0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
321d0 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
321e0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
321f0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
32200 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
32210 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
32220 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
32230 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
32240 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
32250 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
32260 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
32270 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
32280 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
32290 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
322a0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
322b0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
322c0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
322d0 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
322e0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
322f0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
32300 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
32310 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
32320 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
32330 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
32340 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
32350 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
32360 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
32370 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
32380 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
32390 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
323a0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
323b0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
323c0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
323d0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
323e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
323f0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
32400 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
32410 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
32420 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
32430 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32440 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
32450 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
32460 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
32470 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
32480 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
32490 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
324a0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
324b0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
324c0 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71  ng any of.** [sq
324d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
324e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
324f0 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
32500 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
32510 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  v2()],.** or [sq
32520 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
32530 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v3()] or one of 
32540 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
32550 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
32560 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
32570 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32580 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
32590 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
325a0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
325b0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
325c0 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
325d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
325e0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
325f0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
32600 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
32610 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
32620 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
32630 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
32640 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
32650 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65 72  newer "vX" inter
32660 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  faces.** [sqlite
32670 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
32680 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32690 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
326a0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
326b0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
326c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
326d0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
326e0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
326f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32700 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
32710 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
32720 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
32730 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65  ** new "vX" inte
32740 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
32750 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
32760 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
32770 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
32780 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
32790 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
327a0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
327b0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
327c0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
327d0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
327e0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
327f0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
32800 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
32810 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
32820 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
32830 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
32840 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
32850 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
32860 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
32870 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
32880 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
32890 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
328a0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
328b0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
328c0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
328d0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
328e0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
328f0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
32900 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
32910 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
32920 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
32930 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
32940 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
32950 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
32960 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
32970 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
32980 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
32990 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
329a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
329b0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
329c0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
329d0 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
329e0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
329f0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
32a00 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
32a10 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
32a20 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
32a30 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
32a40 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
32a50 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
32a60 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
32a70 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
32a80 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
32a90 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
32aa0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
32ab0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
32ac0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
32ad0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
32ae0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
32af0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
32b00 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
32b10 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
32b20 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
32b30 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
32b40 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
32b50 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
32b60 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
32b70 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
32b80 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
32b90 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
32ba0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
32bb0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
32bc0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
32bd0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
32be0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
32bf0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
32c00 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
32c10 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
32c20 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
32c30 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
32c40 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
32c50 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
32c60 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
32c70 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
32c80 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
32c90 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
32ca0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
32cb0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
32cc0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
32cd0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
32ce0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
32cf0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
32d00 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
32d10 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
32d20 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
32d30 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
32d40 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
32d50 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
32d60 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
32d70 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
32d80 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
32d90 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
32da0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
32db0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
32dc0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
32dd0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
32de0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
32df0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
32e00 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
32e10 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
32e20 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
32e30 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
32e40 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
32e50 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
32e60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
32e70 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
32e80 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
32e90 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
32ea0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
32eb0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
32ec0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
32ed0 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
32ee0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
32ef0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
32f00 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
32f10 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
32f20 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
32f30 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
32f40 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
32f50 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
32f60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
32f70 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
32f80 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
32f90 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
32fa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32fb0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
32fc0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
32fd0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
32fe0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
32ff0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
33000 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
33010 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
33020 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
33030 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
33040 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33050 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
33060 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
33070 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
33080 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
33090 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
330a0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
330b0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
330c0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
330d0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
330e0 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
330f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33100 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
33110 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
33120 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
33130 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
33140 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
33150 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
33160 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73   But after [vers
33170 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b  ion 3.6.23.1] ([
33180 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d  dateof:3.6.23.1]
33190 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ,.** sqlite3_ste
331a0 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
331b0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
331c0 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
331d0 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
331e0 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
331f0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
33200 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
33210 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
33220 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
33230 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
33240 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
33250 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
33260 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
33270 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
33280 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
33290 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
332a0 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
332b0 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
332c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
332d0 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
332e0 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
332f0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
33300 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
33310 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
33320 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
33330 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
33340 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
33350 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
33360 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
33370 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
33380 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
33390 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
333a0 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
333b0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
333c0 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
333d0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
333e0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
333f0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
33400 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
33410 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
33420 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
33430 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
33440 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
33450 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
33460 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
33470 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
33480 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
33490 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
334a0 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
334b0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
334c0 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
334d0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
334e0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
334f0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ts.** using [sql
33500 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
33510 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
33520 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
33530 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
33540 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b  are16_v2()] or [
33550 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
33560 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v3()] instead.
33570 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
33580 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33590 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
335a0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
335b0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
335c0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
335d0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
335e0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
335f0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
33600 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
33610 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
33620 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20 69  vX" interfaces i
33630 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
33640 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
33650 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
33660 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33670 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
33680 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
33690 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
336a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
336b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
336c0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
336d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
336e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
336f0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
33700 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
33710 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
33720 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
33730 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
33740 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
33750 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
33760 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
33770 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
33780 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
33790 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
337a0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
337b0 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
337c0 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
337d0 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
337e0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
337f0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
33800 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
33810 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
33820 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
33830 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
33840 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33850 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
33860 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
33870 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
33880 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
33890 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
338a0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
338b0 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
338c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
338d0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
338e0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
338f0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
33900 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
33910 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
33920 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
33930 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
33940 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
33950 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
33960 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
33970 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
33980 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
33990 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
339a0 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
339b0 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
339c0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
339d0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
339e0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
339f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
33a00 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
33a10 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
33a20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33a30 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
33a40 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
33a50 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
33a60 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
33a70 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
33a80 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
33a90 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
33aa0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
33ab0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
33ac0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
33ad0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
33ae0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
33af0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
33b00 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
33b10 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
33b20 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
33b30 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
33b40 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
33b50 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
33b60 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
33b70 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
33b80 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
33b90 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
33ba0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
33bb0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
33bc0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
33bd0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
33be0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
33bf0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
33c00 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
33c10 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
33c20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
33c30 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
33c40 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
33c50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33c60 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
33c70 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
33c80 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
33c90 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
33ca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
33cb0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
33cc0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
33cd0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
33ce0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
33cf0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
33d00 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
33d10 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
33d20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
33d30 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
33d40 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
33d50 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
33d60 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
33d70 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
33d80 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
33d90 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a  *.** <b>Summary:
33da0 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  </b>.** <blockqu
33db0 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65  ote><table borde
33dc0 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  r=0 cellpadding=
33dd0 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e  0 cellspacing=0>
33de0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33e00 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ob</b><td>&rarr;
33e10 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a  <td>BLOB result.
33e20 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
33e30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
33e40 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  ble</b><td>&rarr
33e50 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74  ;<td>REAL result
33e60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33e70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
33e80 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  t</b><td>&rarr;<
33e90 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45  td>32-bit INTEGE
33ea0 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  R result.** <tr>
33eb0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
33ec0 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c  olumn_int64</b><
33ed0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d  td>&rarr;<td>64-
33ee0 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75  bit INTEGER resu
33ef0 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
33f00 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
33f10 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  text</b><td>&rar
33f20 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54  r;<td>UTF-8 TEXT
33f30 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
33f40 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
33f50 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c  lumn_text16</b><
33f60 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
33f70 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a  -16 TEXT result.
33f80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
33f90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
33fa0 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ue</b><td>&rarr;
33fb0 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61  <td>The result a
33fc0 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  s an .** [sqlite
33fd0 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63  3_value|unprotec
33fe0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
33ff0 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74  e] object..** <t
34000 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e  r><td>&nbsp;<td>
34010 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b  &nbsp;<td>&nbsp;
34020 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34040 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  tes</b><td>&rarr
34050 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42  ;<td>Size of a B
34060 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d  LOB.** or a UTF-
34070 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e  8 TEXT result in
34080 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74   bytes.** <tr><t
34090 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
340a0 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70  umn_bytes16&nbsp
340b0 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c  ;&nbsp;</b>.** <
340c0 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26  td>&rarr;&nbsp;&
340d0 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  nbsp;<td>Size of
340e0 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20   UTF-16.** TEXT 
340f0 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e  in bytes.** <tr>
34100 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
34110 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74  olumn_type</b><t
34120 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61  d>&rarr;<td>Defa
34130 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20  ult.** datatype 
34140 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  of the result.**
34150 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b   </table></block
34160 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  quote>.**.** <b>
34170 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a  Details:</b>.**.
34180 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
34190 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
341a0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
341b0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
341c0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
341d0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
341e0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
341f0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
34200 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
34210 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
34220 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34230 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
34240 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
34250 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
34260 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
34270 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
34280 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
34290 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
342a0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
342b0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
342c0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
342d0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
342e0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
342f0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
34300 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
34310 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
34320 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
34330 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
34340 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
34350 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
34360 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
34370 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
34380 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
34390 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
343a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
343b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
343c0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
343d0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
343e0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
343f0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
34400 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
34410 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
34420 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
34430 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
34440 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
34450 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
34460 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
34470 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
34480 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
34490 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
344a0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
344b0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
344c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
344d0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
344e0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
344f0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
34500 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
34510 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
34520 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
34530 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
34540 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
34550 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
34560 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
34570 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
34580 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
34590 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
345a0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
345b0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
345c0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
345d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
345e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
345f0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
34600 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
34610 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
34620 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
34630 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
34640 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
34650 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
34660 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
34670 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20 69   The first six i
34680 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62  nterfaces (_blob
34690 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c  , _double, _int,
346a0 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20   _int64, _text, 
346b0 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20  and _text16).** 
346c0 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65 20  each return the 
346d0 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c  value of a resul
346e0 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70  t column in a sp
346f0 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d  ecific data form
34700 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72  at.  If.** the r
34710 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
34720 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e  not initially in
34730 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 66   the requested f
34740 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70  ormat (for examp
34750 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75  le,.** if the qu
34760 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ery returns an i
34770 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20 73  nteger but the s
34780 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
34790 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  xt() interface.*
347a0 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78 74  * is used to ext
347b0 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29 20  ract the value) 
347c0 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69  then an automati
347d0 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  c type conversio
347e0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
347f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34800 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
34810 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
34820 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
34830 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
34840 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
34850 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
34860 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
34870 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
34880 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
34890 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
348a0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
348b0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
348c0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
348d0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
348e0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a   [SQLITE_NULL]..
348f0 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  ** The return va
34900 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  lue of sqlite3_c
34910 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e  olumn_type() can
34920 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63 69   be used to deci
34930 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74  de which.** of t
34940 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74  he first six int
34950 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65  erface should be
34960 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74   used to extract
34970 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75   the column valu
34980 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  e..** The value 
34990 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
349a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
349b0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
349c0 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75  gful if no.** au
349d0 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e  tomatic type con
349e0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
349f0 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20 76  curred for the v
34a00 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e  alue in question
34a10 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74  .  .** After a t
34a20 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20  ype conversion, 
34a30 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61  the result of ca
34a40 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  lling sqlite3_co
34a50 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69  lumn_type().** i
34a60 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f  s undefined, tho
34a70 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46  ugh harmless.  F
34a80 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
34a90 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
34aa0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
34ab0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
34ac0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
34ad0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
34ae0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
34af0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
34b00 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20   is a BLOB or a 
34b10 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65  TEXT string, the
34b20 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
34b30 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
34b40 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
34b50 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74 65  n_bytes16() inte
34b60 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75 73  rfaces can be us
34b70 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ed to determine 
34b80 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74  the size.** of t
34b90 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
34ba0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ng..**.** ^If th
34bb0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
34bc0 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
34bd0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
34be0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34bf0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
34c00 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
34c10 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
34c20 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
34c30 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
34c40 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
34c50 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
34c60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34c70 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
34c80 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
34c90 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
34ca0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
34cb0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
34cc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34cd0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
34ce0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34cf0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
34d00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
34d10 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
34d20 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
34d30 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
34d40 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
34d50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34d60 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
34d70 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
34d80 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
34d90 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34da0 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
34db0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
34dc0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34dd0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
34de0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
34df0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34e00 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
34e10 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
34e20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
34e30 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
34e40 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
34e50 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
34e60 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
34e70 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34e80 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
34e90 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
34ea0 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
34eb0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
34ec0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34ed0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
34ee0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
34ef0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
34f00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34f10 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
34f20 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
34f30 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
34f40 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
34f50 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
34f60 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
34f70 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
34f80 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
34f90 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
34fa0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
34fb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34fc0 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
34fd0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
34fe0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
34ff0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
35000 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
35010 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
35020 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
35030 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
35040 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
35050 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
35060 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
35070 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
35080 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
35090 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
350a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
350b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
350c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
350d0 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
350e0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
350f0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
35100 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
35110 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
35120 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
35130 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
35140 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
35150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35160 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
35170 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
35180 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
35190 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
351a0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
351b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
351c0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
351d0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
351e0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
351f0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
35200 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
35210 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
35220 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
35230 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
35240 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
35250 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
35260 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
35270 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
35280 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
35290 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
352a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
352b0 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
352c0 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
352d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
352e0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
352f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35300 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
35310 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
35320 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
35330 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
35340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
35350 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
35360 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
35370 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
35380 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
35390 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
353a0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
353b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
353c0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
353d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
353e0 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
353f0 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
35400 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65  adsafe..** Hence
35410 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  , the sqlite3_co
35420 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74  lumn_value() int
35430 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72  erface.** is nor
35440 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75  mally only usefu
35450 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70  l within the imp
35460 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a  lementation of .
35470 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ** [application-
35480 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
35490 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75  tions] or [virtu
354a0 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20  al tables], not 
354b0 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65  within.** top-le
354c0 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  vel application 
354d0 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  code..**.** The 
354e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  these routines m
354f0 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  ay attempt to co
35500 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74 79  nvert the dataty
35510 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  pe of the result
35520 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c  ..** ^For exampl
35530 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
35540 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
35550 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
35560 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
35570 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
35580 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
35590 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
355a0 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
355b0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
355c0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
355d0 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
355e0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
355f0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
35600 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
35610 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
35620 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
35630 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
35640 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
35650 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
35660 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
35670 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
35680 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
35690 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
356a0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
356b0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
356c0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
356d0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
356e0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
356f0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
35700 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
35710 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
35720 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
35730 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
35740 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
35750 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
35760 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
35770 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
35780 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
35790 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
357a0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
357b0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
357c0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
357d0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
357e0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
357f0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
35800 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
35810 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
35820 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
35830 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
35840 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
35850 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
35860 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
35870 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
35880 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
35890 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
358a0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
358b0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
358c0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
358d0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
358e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
358f0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
35900 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
35910 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
35920 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
35930 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
35940 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
35950 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
35960 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
35970 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
35980 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
35990 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
359a0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
359b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
359c0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
359d0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
359e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
359f0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
35a00 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35a10 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
35a20 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
35a30 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
35a40 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
35a50 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
35a60 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
35a70 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
35a80 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
35a90 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
35aa0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
35ab0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
35ac0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
35ad0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
35ae0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
35af0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
35b00 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
35b10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
35b20 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
35b30 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
35b40 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
35b50 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
35b60 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
35b70 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
35b80 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
35b90 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
35ba0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
35bb0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
35bc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35bd0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
35be0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
35bf0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
35c00 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
35c10 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
35c20 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
35c30 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
35c40 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
35c50 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
35c60 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
35c70 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
35c80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
35c90 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
35ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35cb0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
35cc0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
35cd0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
35ce0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
35cf0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
35d00 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
35d10 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
35d20 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
35d30 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
35d40 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
35d50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
35d60 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
35d70 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
35d80 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
35d90 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
35da0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
35db0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
35dc0 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
35dd0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
35de0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
35df0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
35e00 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
35e10 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
35e20 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
35e30 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
35e40 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
35e50 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
35e60 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
35e70 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
35e80 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
35e90 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
35ea0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
35eb0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
35ec0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
35ed0 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
35ee0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
35ef0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
35f00 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
35f10 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
35f20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
35f30 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
35f40 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
35f50 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
35f60 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
35f70 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
35f80 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
35f90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
35fa0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
35fb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35fc0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
35fd0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
35fe0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
35ff0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
36000 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
36010 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
36020 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
36030 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
36040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36050 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
36060 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
36070 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
36080 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
36090 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
360a0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
360b0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
360c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
360d0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
360e0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
360f0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
36100 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
36110 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
36120 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
36130 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
36140 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
36150 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
36160 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
36170 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
36180 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
36190 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
361a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
361b0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
361c0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
361d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
361e0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
361f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
36200 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
36210 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
36220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36230 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
36240 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
36250 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
36260 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
36270 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
36280 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
36290 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
362a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
362b0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
362c0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
362d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
362e0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
362f0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
36300 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
36310 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
36320 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
36330 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70  cally.  Do not p
36340 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
36350 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
36360 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
36370 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
36380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
36390 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
363a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
363b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
363c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
363d0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
363e0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
363f0 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
36400 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
36410 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
36420 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
36430 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
36440 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
36450 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
36460 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
36470 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
36480 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
36490 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
364a0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
364b0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
364c0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
364d0 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
364e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
364f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
36500 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36510 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
36520 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36530 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
36540 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36550 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
36560 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
36570 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36580 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
36590 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
365a0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
365b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
365c0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
365d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
365e0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
365f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36600 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
36610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36620 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
36630 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
36640 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
36650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
36660 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
36670 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
36680 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36690 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
366a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
366b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
366c0 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
366d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
366e0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
366f0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
36700 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36710 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
36720 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
36730 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
36740 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45  ent Object.** DE
36750 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
36760 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
36770 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
36780 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
36790 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
367a0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
367b0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
367c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
367d0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
367e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
367f0 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
36800 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
36810 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
36820 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
36830 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
36840 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
36850 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
36860 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
36870 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
36880 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
36890 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
368a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
368b0 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
368c0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
368d0 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
368e0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
368f0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
36900 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
36910 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
36920 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
36930 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
36940 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
36950 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
36960 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
36970 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
36980 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
36990 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
369a0 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
369b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
369c0 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
369d0 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
369e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
369f0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
36a00 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
36a10 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
36a20 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
36a30 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
36a40 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
36a50 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
36a60 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
36a70 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
36a80 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
36a90 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
36aa0 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
36ab0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
36ac0 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
36ad0 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
36ae0 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
36af0 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
36b00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
36b10 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
36b20 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
36b30 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
36b40 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
36b50 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
36b60 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
36b70 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
36b80 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
36b90 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
36ba0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
36bb0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
36bc0 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
36bd0 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
36be0 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
36bf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
36c00 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
36c10 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
36c20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
36c30 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
36c40 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
36c50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
36c60 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65  3_stmt.**.** The
36c70 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
36c80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
36c90 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
36ca0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36cb0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
36cc0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
36cd0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
36ce0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
36cf0 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
36d00 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
36d10 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
36d20 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
36d30 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
36d40 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
36d50 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
36d60 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
36d70 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
36d80 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
36d90 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
36da0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
36db0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
36dc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
36dd0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
36de0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
36df0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
36e00 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
36e10 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
36e20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
36e30 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
36e40 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
36e50 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
36e60 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
36e70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
36e80 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
36e90 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
36ea0 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
36eb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
36ec0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
36ed0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
36ee0 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
36ef0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
36f00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
36f10 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
36f20 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
36f30 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
36f40 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
36f50 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
36f60 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
36f70 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
36f80 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
36f90 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
36fa0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
36fb0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
36fc0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
36fd0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
36fe0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
36ff0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
37000 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
37010 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
37020 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
37030 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
37040 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
37050 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
37060 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
37070 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37080 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
37090 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
370a0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
370b0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
370c0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
370d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
370e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
370f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
37100 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
37110 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37120 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
37130 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37140 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
37150 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
37160 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
37170 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
37180 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
37190 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
371a0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
371b0 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
371c0 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
371d0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
371e0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
371f0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
37200 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
37210 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
37220 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
37230 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
37240 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
37250 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
37260 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
37270 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
37280 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
37290 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
372a0 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
372b0 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
372c0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
372d0 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
372e0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
372f0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
37300 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
37310 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
37320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
37330 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
37340 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
37350 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
37360 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
37370 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
37380 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
37390 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
373a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
373b0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
373c0 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
373d0 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
373e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
373f0 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
37400 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
37410 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
37420 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
37430 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
37440 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
37450 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
37460 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
37470 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
37480 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
37490 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
374a0 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
374b0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
374c0 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
374d0 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
374e0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
374f0 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
37500 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
37510 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
37520 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
37530 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
37540 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
37550 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
37560 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
37570 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
37580 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
37590 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
375a0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
375b0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
375c0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
375d0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
375e0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
375f0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
37600 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
37610 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
37620 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
37630 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
37640 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
37650 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
37660 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
37670 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
37680 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
37690 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
376a0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
376b0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
376c0 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
376d0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
376e0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
376f0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
37700 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
37710 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
37720 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
37730 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
37740 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
37750 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
37760 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
37770 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
37780 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
37790 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
377a0 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
377b0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
377c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
377d0 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
377e0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
377f0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
37800 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
37810 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
37820 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
37830 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
37840 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
37850 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
37860 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37870 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
37880 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
37890 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
378a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
378b0 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
378c0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
378d0 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
378e0 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
378f0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
37900 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
37910 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
37920 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
37930 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
37940 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
37950 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
37960 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
37970 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
37980 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
37990 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
379a0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
379b0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
379c0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
379d0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
379e0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
379f0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
37a00 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
37a10 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
37a20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
37a30 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
37a40 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
37a50 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
37a60 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
37a70 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
37a80 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
37a90 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
37aa0 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
37ab0 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
37ac0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
37ad0 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
37ae0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
37af0 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
37b00 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
37b10 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
37b20 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
37b30 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
37b40 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
37b50 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
37b60 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
37b70 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
37b80 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
37b90 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
37ba0 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
37bb0 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
37bc0 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
37bd0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
37be0 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
37bf0 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
37c00 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
37c10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
37c20 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
37c30 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
37c40 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
37c50 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
37c60 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
37c70 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
37c80 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
37c90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
37ca0 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
37cb0 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
37cc0 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
37cd0 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
37ce0 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
37cf0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
37d00 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
37d10 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
37d20 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
37d30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
37d40 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
37d50 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
37d60 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
37d70 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
37d80 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
37d90 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
37da0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
37db0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
37dc0 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
37dd0 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
37de0 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
37df0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
37e00 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
37e10 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
37e20 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
37e30 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
37e40 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
37e50 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
37e60 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
37e70 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
37e80 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
37e90 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
37ea0 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
37eb0 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
37ec0 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
37ed0 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
37ee0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37ef0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
37f00 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
37f10 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
37f20 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
37f30 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
37f40 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
37f50 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
37f60 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
37f70 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
37f80 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
37f90 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
37fa0 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
37fb0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
37fc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
37fd0 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
37fe0 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
37ff0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
38000 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
38010 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38020 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
38030 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
38040 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
38050 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
38060 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
38070 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
38080 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
38090 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
380a0 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
380b0 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
380c0 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
380d0 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
380e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
380f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
38100 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
38110 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
38120 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
38130 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
38140 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
38150 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
38160 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
38170 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
38180 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
38190 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
381a0 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
381b0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
381c0 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
381d0 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
381e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
381f0 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
38200 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
38210 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
38220 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
38230 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
38240 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
38250 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
38260 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
38270 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
38280 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
38290 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
382a0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
382b0 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
382c0 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
382d0 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
382e0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
382f0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
38300 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
38310 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
38320 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
38330 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
38340 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
38350 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
38360 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
38370 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
38380 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
38390 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
383a0 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
383b0 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
383c0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
383d0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
383e0 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
383f0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
38400 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
38410 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
38420 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
38430 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
38440 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
38450 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
38460 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
38470 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
38480 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
38490 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
384a0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
384b0 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
384c0 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
384d0 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
384e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
384f0 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
38500 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
38510 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
38520 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
38530 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
38540 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
38550 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
38560 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
38570 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
38580 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
38590 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
385a0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
385b0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
385c0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
385d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
385e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
385f0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
38600 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38610 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
38620 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
38630 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
38640 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
38650 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
38660 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
38670 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
38680 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
38690 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
386a0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
386b0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
386c0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
386d0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
386e0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
386f0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
38700 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
38710 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
38720 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
38730 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
38740 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
38750 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
38760 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
38770 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33