System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 2fc9f088e1b8a17f67f001a2b89c50b738e82d5c:


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 33 2e 32 33 2e 31 22 0a 23 64 65      "3.23.1".#de
1210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1220: 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 32 33 30  ION_NUMBER 30230
1230: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
1240: 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20  E_SOURCE_ID     
1250: 20 22 32 30 31 38 2d 30 34 2d 31 30 20 31 37 3a   "2018-04-10 17:
1260: 33 39 3a 32 39 20 34 62 62 32 32 39 34 30 32 32  39:29 4bb2294022
1270: 30 36 30 65 36 31 64 65 37 64 61 35 63 32 32 37  060e61de7da5c227
1280: 61 36 39 63 63 64 38 34 36 62 61 33 33 30 65 33  a69ccd846ba330e3
1290: 31 36 32 36 65 62 63 64 35 39 61 39 34 65 66 64  1626ebcd59a94efd
12a0: 31 34 38 62 33 62 22 0a 0a 2f 2a 0a 2a 2a 20 43  148b3b"../*.** C
12b0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
12c0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
12d0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
12e0: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
12f0: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1300: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1310: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1320: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1330: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1340: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1350: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1360: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1370: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1380: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1390: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
13a0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
13b0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
13c0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
13d0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
13e0: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
13f0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1400: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1410: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1420: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1430: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1440: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1450: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1460: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1470: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1480: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1490: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
14a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14b0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
14c0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
14d0: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
14e0: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
14f0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1500: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1510: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1520: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1530: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1540: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 6e  .** assert( strn
1550: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1560: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1570: 55 52 43 45 5f 49 44 2c 38 30 29 3d 3d 30 20 29  URCE_ID,80)==0 )
1580: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1590: 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76  cmp(sqlite3_libv
15a0: 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f  ersion(),SQLITE_
15b0: 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a  VERSION)==0 );.*
15c0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15d0: 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
15e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
15f0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1600: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
1610: 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54  e text of [SQLIT
1620: 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61  E_VERSION].** ma
1630: 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  cro.  ^The sqlit
1640: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20  e3_libversion() 
1650: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1660: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1670: 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69  e.** to the sqli
1680: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1690: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
16a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
16b0: 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63  ersion().** func
16c0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
16d0: 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73   for use in DLLs
16e0: 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73   since DLL users
16f0: 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20   usually do not 
1700: 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61  have.** direct a
1710: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20  ccess to string 
1720: 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e  constants within
1730: 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a   the DLL.  ^The.
1740: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
1750: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66  rsion_number() f
1760: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1770: 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c  an integer equal
1780: 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56   to.** [SQLITE_V
1790: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20  ERSION_NUMBER]. 
17a0: 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
17b0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
17c0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
17d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
17e0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
17f0: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1800: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1810: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1820: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1830: 6f 72 20 6d 61 63 72 6f 2e 20 20 45 78 63 65 70  or macro.  Excep
1840: 74 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 62  t if SQLite is b
1850: 75 69 6c 74 0a 2a 2a 20 75 73 69 6e 67 20 61 6e  uilt.** using an
1860: 20 65 64 69 74 65 64 20 63 6f 70 79 20 6f 66 20   edited copy of 
1870: 5b 74 68 65 20 61 6d 61 6c 67 61 6d 61 74 69 6f  [the amalgamatio
1880: 6e 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 61 73  n], then the las
1890: 74 20 66 6f 75 72 20 63 68 61 72 61 63 74 65 72  t four character
18a0: 73 0a 2a 2a 20 6f 66 20 74 68 65 20 68 61 73 68  s.** of the hash
18b0: 20 6d 69 67 68 74 20 62 65 20 64 69 66 66 65 72   might be differ
18c0: 65 6e 74 20 66 72 6f 6d 20 5b 53 51 4c 49 54 45  ent from [SQLITE
18d0: 5f 53 4f 55 52 43 45 5f 49 44 5d 2e 29 5e 0a 2a  _SOURCE_ID].)^.*
18e0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
18f0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
1900: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
1910: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1920: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1930: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1940: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1950: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1960: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
1970: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1980: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
1990: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
19a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
19b0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
19c0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62   int sqlite3_lib
19d0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
19e0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
19f0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1a00: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
1a10: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
1a20: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
1a30: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
1a40: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
1a50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a60: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
1a70: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
1a80: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
1a90: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
1aa0: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
1ab0: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
1ac0: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
1ad0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
1ae0: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
1af0: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
1b00: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
1b20: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
1b50: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
1b60: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
1b70: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
1b80: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
1b90: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
1ba0: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
1bb0: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
1bc0: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
1bd0: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
1be0: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
1bf0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c00: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
1c10: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1c20: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
1c30: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
1c40: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
1c50: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1c60: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1c70: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
1c80: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
1c90: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
1ca0: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
1cb0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1cc0: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
1cd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ce0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
1cf0: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
1d00: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
1d10: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
1d20: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d30: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
1d40: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
1d50: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
1d60: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
1d70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1d80: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1d90: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
1da0: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
1db0: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
1dc0: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
1dd0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
1de0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1df0: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
1e00: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1e10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1e20: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1e30: 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45  OptName);.SQLITE
1e40: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
1e50: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1e60: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1e70: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1e80: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1e90: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1ea0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1eb0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1ec0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1ed0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1ee0: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1ef0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1f00: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1f10: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1f20: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1f30: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1f40: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1f50: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1f60: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1f70: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1f80: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1f90: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1fa0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1fb0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1fc0: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1fd0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1fe0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1ff0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
2000: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
2010: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
2020: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
2030: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
2040: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
2050: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
2060: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
2070: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
2080: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
2090: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
20a0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
20b0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
20c0: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
20d0: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
20e0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
20f0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
2100: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
2110: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
2120: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
2130: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
2140: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
2150: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
2160: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
2170: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
2180: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
2190: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
21a0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
21b0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
21c0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
21d0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
21e0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
21f0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
2200: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
2210: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
2220: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
2230: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2240: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2250: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
2260: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
2270: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
2280: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2290: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
22a0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
22b0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
22c0: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
22d0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
22e0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
22f0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2300: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
2310: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
2320: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
2330: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2340: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2350: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2360: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2370: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2380: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2390: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
23a0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
23b0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
23c0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
23d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
23e0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
23f0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
2400: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2410: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2420: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2430: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2440: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2450: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2460: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2470: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2480: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2490: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
24a0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
24b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
24c0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
24d0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
24e0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
24f0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2500: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2510: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2520: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2530: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2540: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2550: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2560: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2570: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2580: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2590: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
25a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
25b0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
25c0: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
25d0: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
25e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
25f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2600: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2610: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2620: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2630: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2640: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2650: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2660: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2670: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2680: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2690: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
26a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
26b0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
26c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
26d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
26e0: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
26f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2700: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2710: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2720: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2730: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2740: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2750: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
2760: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
2770: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
2780: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
2790: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
27a0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
27b0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27c0: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
27d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
27e0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
27f0: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2800: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2810: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2820: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2830: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2840: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2850: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
2860: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
2870: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
2880: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2890: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
28a0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
28b0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
28c0: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
28d0: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
28e0: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
28f0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2900: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2910: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2920: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2930: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2940: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2950: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
2960: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
2970: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
2980: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
2990: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
29a0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
29b0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
29c0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
29d0: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
29e0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
29f0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2a00: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2a10: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2a20: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2a30: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2a40: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2a50: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
2a60: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
2a70: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
2a80: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2a90: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
2aa0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
2ab0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2ac0: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2ad0: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2ae0: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2af0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2b00: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2b30: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2b40: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2b50: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
2b60: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2b70: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
2b80: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2b90: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2ba0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
2bb0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2bc0: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2bd0: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2be0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2bf0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2c00: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c10: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2c30: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2c40: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2c50: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2c60: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2c70: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2c80: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2c90: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ca0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2cb0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2cc0: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2cd0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2ce0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2cf0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2d00: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2d10: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2d20: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2d30: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2d40: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2d50: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2d60: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2d70: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2d80: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2d90: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2da0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2db0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2dc0: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2dd0: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2de0: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2df0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2e00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2e10: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2e20: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2e30: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2e40: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2e50: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2e60: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2e70: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2e80: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2e90: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ea0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2eb0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2ec0: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2ed0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2ee0: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2ef0: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2f00: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f10: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2f20: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2f30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2f40: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2f50: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2f60: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2f70: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2f80: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2f90: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2fa0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2fb0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2fc0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2fd0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2fe0: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2ff0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
3000: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
3010: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
3020: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
3030: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
3040: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
3050: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
3060: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
3070: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
3080: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
3090: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
30a0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
30b0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
30c0: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
30d0: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
30e0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
30f0: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
3100: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
3110: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
3120: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
3130: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
3140: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
3150: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
3160: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
3170: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
3180: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
3190: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
31a0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
31b0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
31c0: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
31d0: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
31e0: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
31f0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3200: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3210: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3220: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3230: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3240: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3250: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
3260: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3270: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
3280: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
3290: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
32a0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
32b0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
32c0: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
32d0: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
32e0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
32f0: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3300: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3310: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3320: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3330: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3340: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3350: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
3360: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3370: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
3380: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
3390: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
33a0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
33b0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
33c0: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
33d0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
33e0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
33f0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3400: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3410: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3420: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3430: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3440: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3450: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
3460: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
3470: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
3480: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
3490: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
34a0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
34b0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
34c0: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
34d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
34e0: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
34f0: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3500: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3510: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3520: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3530: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3540: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3550: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
3560: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
3570: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
3580: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
3590: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
35a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
35b0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
35c0: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
35d0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
35e0: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
35f0: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
3600: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
3610: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3620: 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
3630: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
3640: 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a  e_v2(sqlite3*);.
3650: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
3660: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
3670: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
3680: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
3690: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
36a0: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
36b0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
36c0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
36d0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
36e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
36f0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
3700: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
3710: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
3720: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3730: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
3740: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
3750: 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ace.** METHOD: s
3760: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
3770: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3780: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
3790: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
37a0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
37b0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
37c0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
37d0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
37e0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
37f0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3800: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3810: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3820: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3830: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3840: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3850: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3860: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3870: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3880: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3890: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
38a0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
38b0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
38c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
38d0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
38e0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
38f0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3900: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3910: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3920: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3930: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3940: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3950: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3960: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3970: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3980: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3990: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
39a0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
39b0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
39c0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
39d0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
39e0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
39f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3a00: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3a10: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3a20: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3a30: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3a40: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3a50: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3a60: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3a70: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3a80: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3a90: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3aa0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3ab0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3ac0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3ad0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3ae0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3af0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3b00: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3b20: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3b30: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3b40: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3b50: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3b60: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3b70: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3b90: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3ba0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3bb0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3bc0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3bd0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3be0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3bf0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3c00: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3c10: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3c20: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3c30: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3c40: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3c50: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3c60: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3c70: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3c80: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3c90: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3ca0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3cb0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69  meter of.** sqli
3cc0: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72  te3_exec() after
3cd0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
3ce0: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20  ge string is no 
3cf0: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a  longer needed..*
3d00: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61  * ^If the 5th pa
3d10: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3d20: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
3d30: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72   NULL and no err
3d40: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68  ors.** occur, th
3d50: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  en sqlite3_exec(
3d60: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74  ) sets the point
3d70: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61  er in its 5th pa
3d80: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55  rameter to.** NU
3d90: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  LL before return
3da0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  ing..**.** ^If a
3db0: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3dc0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
3dd0: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
3de0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3df0: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
3e00: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77  s SQLITE_ABORT w
3e10: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20  ithout invoking 
3e20: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61  the callback aga
3e30: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75  in and.** withou
3e40: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75  t running any su
3e50: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
3e60: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
3e70: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  The 2nd argument
3e80: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3e90: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3ea0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a  function is the.
3eb0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  ** number of col
3ec0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
3ed0: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72  lt.  ^The 3rd ar
3ee0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3f00: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3f10: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3f20: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61   to strings obta
3f30: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a  ined as if from.
3f40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
3f50: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20  mn_text()], one 
3f60: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e  for each column.
3f70: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74    ^If an element
3f80: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20   of a.** result 
3f90: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  row is NULL then
3fa0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
3fb0: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ng string pointe
3fc0: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c  r for the.** sql
3fd0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3fe0: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70  back is a NULL p
3ff0: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74  ointer.  ^The 4t
4000: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
4010: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
4020: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
4030: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
4040: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
4050: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e  where each.** en
4060: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74  try represents t
4070: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65  he name of corre
4080: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20  sponding result 
4090: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e  column as obtain
40a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
40b0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
40c0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  )]..**.** ^If th
40d0: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
40e0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
40f0: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
4100: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a  ter, a pointer.*
4110: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  * to an empty st
4120: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74  ring, or a point
4130: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  er that contains
4140: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
4150: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20   and/or .** SQL 
4160: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
4170: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
4180: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
4190: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  nd the database.
41a0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
41b0: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63  d..**.** Restric
41c0: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tions:.**.** <ul
41d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  >.** <li> The ap
41e0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65  plication must e
41f0: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31  nsure that the 1
4200: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4210: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
4220: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69  *      is a vali
4230: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61  d and open [data
4240: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
4250: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
4260: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
4270: 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61  ot close the [da
4280: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4290: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  n] specified by.
42a0: 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20  **      the 1st 
42b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
42c0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
42d0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
42e0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
42f0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
4300: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f  tion must not mo
4310: 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61  dify the SQL sta
4320: 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73  tement text pass
4330: 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20  ed into.**      
4340: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
4350: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  r of sqlite3_exe
4360: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
4370: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
4380: 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ing..** </ul>.*/
4390: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
43a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
43b0: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
43e0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
43f0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
4400: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
4410: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4420: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
4430: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28  uated */.  int (
4440: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  *callback)(void*
4450: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
4460: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63  **),  /* Callbac
4470: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  k function */.  
4480: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
4490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44a0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73             /* 1s
44b0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  t argument to ca
44c0: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72  llback */.  char
44d0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
44e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44f0: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
4500: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
4510: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
4520: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43  PI3REF: Result C
4530: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4540: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64  : {result code d
4550: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
4560: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
4570: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
4580: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
4590: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
45a0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
45b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
45c0: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
45d0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
45e0: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
45f0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4600: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4610: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4620: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65   See also: [exte
4630: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4640: 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f   definitions].*/
4650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4660: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
4670: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
4680: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
4690: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
46a0: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
46b0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
46c0: 20 20 20 20 31 20 20 20 2f 2a 20 47 65 6e 65 72      1   /* Gener
46d0: 69 63 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ic error */.#def
46e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
46f0: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
4700: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
4710: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
4720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4730: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
4740: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
4750: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
4760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
4770: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
4780: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
4790: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
47a0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
47c0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
47d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
47e0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
47f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
4800: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
4810: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
4820: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
4830: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4840: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
4850: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
4860: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
4880: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
4890: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
48a0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
48b0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
48c0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
48d0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
48e0: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
48f0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
4900: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
4910: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
4920: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
4930: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
4940: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
4950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4960: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
4970: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4980: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
4990: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
49a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49b0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
49c0: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
49d0: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
49e0: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
49f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
4a00: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
4a10: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
4a20: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
4a30: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
4a50: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
4a60: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
4a70: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
4a80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a90: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
4aa0: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
4ab0: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
4ac0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4ad0: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
4ae0: 20 20 31 36 20 20 20 2f 2a 20 49 6e 74 65 72 6e    16   /* Intern
4af0: 61 6c 20 75 73 65 20 6f 6e 6c 79 20 2a 2f 0a 23  al use only */.#
4b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
4b10: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
4b20: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
4b30: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
4b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b50: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
4b60: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
4b70: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
4b80: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
4b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
4ba0: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
4bb0: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
4bc0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
4bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4be0: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
4bf0: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
4c00: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
4c10: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
4c20: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
4c30: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
4c40: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
4c50: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
4c60: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
4c70: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
4c80: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
4c90: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
4ca0: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
4cb0: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
4cc0: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
4cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ce0: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
4cf0: 20 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a   /* Not used */.
4d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d10: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4d20: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4d30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4d40: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d60: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4d70: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4d80: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4d90: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4db0: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
4dc0: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
4dd0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4de0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4df0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
4e00: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
4e10: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4e20: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4e30: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
4e40: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
4e50: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
4e60: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
4e70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4e80: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
4e90: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
4ea0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
4eb0: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
4ec0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
4ed0: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
4ee0: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
4ef0: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
4f00: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4f10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4f20: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4f30: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4f40: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4f50: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4f60: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4f70: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a  e of 30 integer.
4f80: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  ** [result codes
4f90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4fa0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4fb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4fc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4fd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4fe0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4ff0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
5000: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
5010: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
5020: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
5030: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
5040: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
5050: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
5060: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
5070: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
5080: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61  ersion 3.3.8 [da
5090: 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61  teof:3.3.8].** a
50a0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
50b0: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
50c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
50d0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
50e0: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
50f0: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
5100: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
5110: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
5120: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
5130: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
5140: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
5150: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
5160: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
5170: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
5180: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
5190: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
51a0: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
51b0: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
51c0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
51d0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
51e0: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
51f0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
5200: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
5220: 52 4f 52 5f 4d 49 53 53 49 4e 47 5f 43 4f 4c 4c  ROR_MISSING_COLL
5230: 53 45 51 20 20 20 28 53 51 4c 49 54 45 5f 45 52  SEQ   (SQLITE_ER
5240: 52 4f 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ROR | (1<<8)).#d
5250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
5260: 4f 52 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  OR_RETRY        
5270: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 45 52 52       (SQLITE_ERR
5280: 4f 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  OR | (2<<8)).#de
5290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
52a0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
52b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
52c0: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5310: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5320: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
5330: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5340: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5350: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
5360: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
5370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5380: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5390: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
53a0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
53b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53c0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
53e0: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5400: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5410: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
5420: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
5430: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
5440: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
5460: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
5480: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5490: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
54a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
54b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
54c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
54d0: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
54e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
54f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
5500: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5510: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
5520: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5530: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
5540: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5550: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
5560: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5570: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
5580: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5590: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
55a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
55b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
55c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
55d0: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
55e0: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
55f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
5600: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5610: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
5620: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5630: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
5640: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5650: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
5660: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5670: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
5680: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5690: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
56a0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
56b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
56c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
56e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
5700: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5710: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
5720: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5730: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
5740: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5750: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
5760: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5770: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
5780: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5790: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20  TE_IOERR_SHMMAP 
57a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
57b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c  TE_IOERR | (21<<
57c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
57d0: 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20  TE_IOERR_SEEK   
57e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
57f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c  TE_IOERR | (22<<
5800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5810: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f  TE_IOERR_DELETE_
5820: 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49  NOENT      (SQLI
5830: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c  TE_IOERR | (23<<
5840: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5850: 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20  TE_IOERR_MMAP   
5860: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5870: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c  TE_IOERR | (24<<
5880: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5890: 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50  TE_IOERR_GETTEMP
58a0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
58b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c  TE_IOERR | (25<<
58c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58d0: 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54  TE_IOERR_CONVPAT
58e0: 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  H          (SQLI
58f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c  TE_IOERR | (26<<
5900: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5910: 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20  TE_IOERR_VNODE  
5920: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5930: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c  TE_IOERR | (27<<
5940: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5950: 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20  TE_IOERR_AUTH   
5960: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5970: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c  TE_IOERR | (28<<
5980: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5990: 54 45 5f 49 4f 45 52 52 5f 42 45 47 49 4e 5f 41  TE_IOERR_BEGIN_A
59a0: 54 4f 4d 49 43 20 20 20 20 20 20 28 53 51 4c 49  TOMIC      (SQLI
59b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 39 3c 3c  TE_IOERR | (29<<
59c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
59d0: 54 45 5f 49 4f 45 52 52 5f 43 4f 4d 4d 49 54 5f  TE_IOERR_COMMIT_
59e0: 41 54 4f 4d 49 43 20 20 20 20 20 28 53 51 4c 49  ATOMIC     (SQLI
59f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 30 3c 3c  TE_IOERR | (30<<
5a00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a10: 54 45 5f 49 4f 45 52 52 5f 52 4f 4c 4c 42 41 43  TE_IOERR_ROLLBAC
5a20: 4b 5f 41 54 4f 4d 49 43 20 20 20 28 53 51 4c 49  K_ATOMIC   (SQLI
5a30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 31 3c 3c  TE_IOERR | (31<<
5a40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a50: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
5a60: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
5a70: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5a80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a90: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5aa0: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5ab0: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5ac0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ad0: 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48  LITE_BUSY_SNAPSH
5ae0: 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51  OT           (SQ
5af0: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5b00: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b10: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
5b20: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
5b30: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5b40: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5b50: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5b60: 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20  _ISDIR          
5b70: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5b80: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5b90: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5ba0: 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20  EN_FULLPATH     
5bb0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5bc0: 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  EN | (3<<8)).#de
5bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5be0: 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20  OPEN_CONVPATH   
5bf0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5c00: 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OPEN | (4<<8)).#
5c10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5c20: 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20  RRUPT_VTAB      
5c30: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5c40: 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RRUPT | (1<<8)).
5c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5c60: 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59  EADONLY_RECOVERY
5c70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5c80: 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29  EADONLY | (1<<8)
5c90: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5ca0: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f  _READONLY_CANTLO
5cb0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
5cc0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c  _READONLY | (2<<
5cd0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ce0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c  TE_READONLY_ROLL
5cf0: 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  BACK       (SQLI
5d00: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33  TE_READONLY | (3
5d10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5d20: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42  LITE_READONLY_DB
5d30: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51  MOVED        (SQ
5d40: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5d50: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5d60: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5d70: 43 41 4e 54 49 4e 49 54 20 20 20 20 20 20 20 28  CANTINIT       (
5d80: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5d90: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5da0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5db0: 59 5f 44 49 52 45 43 54 4f 52 59 20 20 20 20 20  Y_DIRECTORY     
5dc0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5dd0: 59 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  Y | (6<<8)).#def
5de0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
5df0: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5e00: 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54     (SQLITE_ABORT
5e10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5e20: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5e30: 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20  AINT_CHECK      
5e40: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5e50: 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AINT | (1<<8)).#
5e60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5e70: 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48  NSTRAINT_COMMITH
5e80: 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  OOK   (SQLITE_CO
5e90: 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38  NSTRAINT | (2<<8
5ea0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5eb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52  E_CONSTRAINT_FOR
5ec0: 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54  EIGNKEY   (SQLIT
5ed0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ee0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ef0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f00: 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53  _FUNCTION     (S
5f10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f20: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5f30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5f40: 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20  AINT_NOTNULL    
5f50: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5f60: 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23  AINT | (5<<8)).#
5f70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5f80: 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59  NSTRAINT_PRIMARY
5f90: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5fa0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38  NSTRAINT | (6<<8
5fb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5fc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49  E_CONSTRAINT_TRI
5fd0: 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54  GGER      (SQLIT
5fe0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ff0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
6000: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6010: 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53  _UNIQUE       (S
6020: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6030: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
6040: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
6050: 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20  AINT_VTAB       
6060: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
6070: 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23  AINT | (9<<8)).#
6080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
6090: 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20  NSTRAINT_ROWID  
60a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
60b0: 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38  NSTRAINT |(10<<8
60c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
60d0: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
60e0: 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54  _WAL      (SQLIT
60f0: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38  E_NOTICE | (1<<8
6100: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
6110: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
6120: 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54  _ROLLBACK (SQLIT
6130: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38  E_NOTICE | (2<<8
6140: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
6150: 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e  E_WARNING_AUTOIN
6160: 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 54  DEX       (SQLIT
6170: 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c  E_WARNING | (1<<
6180: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6190: 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20  TE_AUTH_USER    
61a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
61b0: 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29  TE_AUTH | (1<<8)
61c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
61d0: 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45  _OK_LOAD_PERMANE
61e0: 4e 54 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45  NTLY     (SQLITE
61f0: 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f  _OK | (1<<8))../
6200: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6210: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
6220: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
6230: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
6240: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
6250: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
6260: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
6270: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
6280: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
6290: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
62a0: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
62b0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
62c0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
62d0: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
62e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
62f0: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
6300: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
6310: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6320: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6330: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
6340: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
6350: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
6360: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6370: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6380: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
6390: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
63a0: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
63b0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
63c0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
63d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
63e0: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
63f0: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
6400: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6410: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
6420: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
6430: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
6440: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6450: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
6460: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
6470: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
6480: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6490: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
64a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
64b0: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
64c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
64d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
64e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d   SQLITE_OPEN_MEM
64f0: 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78  ORY           0x
6500: 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20  00000080  /* Ok 
6510: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6520: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6530: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
6540: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
6550: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
6560: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6570: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
6580: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
6590: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
65a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
65b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
65c0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
65d0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
65e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
65f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
6600: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
6610: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
6620: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6630: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
6640: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
6650: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
6660: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6670: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
6680: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
6690: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
66a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
66b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
66c0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
66d0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
66e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
66f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
6700: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
6710: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
6720: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6730: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6740: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
6750: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
6760: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
6770: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6780: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6790: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
67a0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
67b0: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
67c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
67d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
67e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
67f0: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
6800: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
6810: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6820: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6830: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
6840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6850: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
6860: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
6870: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
6880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6890: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
68a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
68b0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
68c0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
68d0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
68e0: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
68f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6900: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
6910: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
6920: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
6930: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65   vector of these
6940: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
6950: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
6960: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
6970: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
6980: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6990: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
69a0: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
69b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
69c0: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
69d0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
69e0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
69f0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
6a00: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
6a10: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
6a20: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6a30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
6a40: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
6a50: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
6a60: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
6a70: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
6a80: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
6a90: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
6aa0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
6ab0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
6ac0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
6ad0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6ae0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6af0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
6b00: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
6b10: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
6b20: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
6b30: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
6b40: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
6b50: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
6b60: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
6b70: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
6b80: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
6b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6ba0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
6bb0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
6bc0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
6bd0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
6be0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
6bf0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
6c00: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
6c10: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6c20: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
6c30: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6c40: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
6c50: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
6c60: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
6c70: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
6c80: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
6c90: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
6ca0: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
6cb0: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
6cc0: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
6cd0: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
6ce0: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
6cf0: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
6d00: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
6d10: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
6d20: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20   be unchanged.  
6d30: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6d40: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6d50: 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69  N_OPEN.** flag i
6d60: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 61 20  ndicates that a 
6d70: 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64  file cannot be d
6d80: 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e  eleted when open
6d90: 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45  .  The.** SQLITE
6da0: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
6db0: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20   flag indicates 
6dc0: 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69 73  that the file is
6dd0: 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79   on.** read-only
6de0: 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f   media and canno
6df0: 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76 65  t be changed eve
6e00: 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20 77  n by processes w
6e10: 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20  ith.** elevated 
6e20: 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a  privileges..**.*
6e30: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
6e40: 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20  AP_BATCH_ATOMIC 
6e50: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6e60: 68 61 74 20 74 68 65 20 75 6e 64 65 72 6c 79 69  hat the underlyi
6e70: 6e 67 0a 2a 2a 20 66 69 6c 65 73 79 73 74 65 6d  ng.** filesystem
6e80: 20 73 75 70 70 6f 72 74 73 20 64 6f 69 6e 67 20   supports doing 
6e90: 6d 75 6c 74 69 70 6c 65 20 77 72 69 74 65 20 6f  multiple write o
6ea0: 70 65 72 61 74 69 6f 6e 73 20 61 74 6f 6d 69 63  perations atomic
6eb0: 61 6c 6c 79 20 77 68 65 6e 20 74 68 6f 73 65 0a  ally when those.
6ec0: 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  ** write operati
6ed0: 6f 6e 73 20 61 72 65 20 62 72 61 63 6b 65 74 65  ons are brackete
6ee0: 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 46 43 4e  d by [SQLITE_FCN
6ef0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
6f00: 57 52 49 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53  WRITE] and.** [S
6f10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
6f20: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IT_ATOMIC_WRITE]
6f30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6f40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6f50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6f60: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
6f70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6f80: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
6f90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6fa0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6fb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6fd0: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6fe0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6ff0: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
7000: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
7010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7020: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
7030: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7040: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
7050: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7060: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
7070: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
7080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7090: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
70a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
70b0: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
70c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
70d0: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
70e0: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
70f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7100: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
7110: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
7120: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
7130: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
7140: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
7150: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
7160: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7170: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
7180: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
7190: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
71a0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
71b0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
71c0: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
71d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
71e0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
71f0: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
7200: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7210: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20  OCAP_IMMUTABLE  
7220: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7230: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53  002000.#define S
7240: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43  QLITE_IOCAP_BATC
7250: 48 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  H_ATOMIC        
7260: 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f     0x00004000../
7270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
7280: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
7290: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
72a0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
72b0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
72c0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
72d0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
72e0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
72f0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
7300: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
7310: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
7320: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7330: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
7340: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
7350: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
7360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7370: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
7380: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
7390: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
73a0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
73b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
73c0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
73d0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
73e0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
73f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7400: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
7410: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
7420: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
7430: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
7440: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
7450: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7460: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
7470: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
7480: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
7490: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
74a0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
74b0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
74c0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
74d0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
74e0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
74f0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
7500: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
7510: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
7520: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
7530: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
7540: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
7550: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
7560: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
7570: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
7580: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
7590: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
75a0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
75b0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
75c0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
75d0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
75e0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
75f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
7600: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
7610: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
7620: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7630: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7640: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7650: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7660: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7670: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7680: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7690: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
76a0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
76b0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
76c0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
76d0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
76e0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
76f0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7700: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
7710: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7720: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7730: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7740: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7750: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7760: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7770: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7780: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7790: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
77a0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
77b0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
77c0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
77d0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
77e0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
77f0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7800: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
7810: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7820: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7830: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7840: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7850: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7860: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7870: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7880: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7890: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
78a0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
78b0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
78c0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
78d0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
78e0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
78f0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7900: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
7910: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7920: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7930: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7940: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7950: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7960: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7970: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7980: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7990: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
79a0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
79b0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
79c0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
79d0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
79e0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
79f0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7a00: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
7a10: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7a20: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7a30: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7a40: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7a50: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7a60: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7a70: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7a80: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7a90: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7aa0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7ab0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7ac0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
7ad0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7ae0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7af0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7b00: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
7b10: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7b20: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7b30: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7b40: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7b50: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7b60: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7b70: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7b80: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7b90: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7ba0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7bb0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7bc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7bd0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
7be0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7bf0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7c00: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
7c10: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7c20: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7c30: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7c40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7c50: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7c60: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7c70: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7c80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7c90: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7ca0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7cb0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7cc0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
7cd0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7ce0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7cf0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7d00: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
7d10: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7d20: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7d30: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7d40: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7d50: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7d60: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7d70: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7d80: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7d90: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7da0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7db0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7dc0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
7dd0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
7de0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7df0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7e00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7e10: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7e20: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7e30: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7e40: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7e50: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7e60: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7e70: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7e80: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7e90: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7ea0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7eb0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7ec0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
7ed0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
7ee0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7ef0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7f00: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
7f10: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7f20: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7f30: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7f40: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7f50: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7f60: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7f70: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7f80: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7f90: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7fa0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7fb0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7fc0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7fd0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7fe0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7ff0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
8000: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
8010: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
8020: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
8030: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
8040: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
8050: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
8060: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
8070: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
8080: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
8090: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
80a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
80b0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
80c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
80d0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
80e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
80f0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
8100: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
8110: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
8120: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
8130: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
8140: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
8150: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
8160: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
8170: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
8180: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
8190: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
81a0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
81b0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
81c0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
81d0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
81e0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
81f0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
8200: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
8210: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
8220: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
8230: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
8240: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
8250: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
8260: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
8270: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
8280: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
8290: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
82a0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
82b0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
82c0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
82d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
82e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
82f0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
8300: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
8310: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
8320: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
8330: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
8340: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
8350: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
8360: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
8370: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
8380: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
8390: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
83a0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
83b0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
83c0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
83d0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
83e0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
83f0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
8400: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
8410: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
8420: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
8430: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
8440: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
8450: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
8460: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
8470: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
8480: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
8490: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
84a0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
84b0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
84c0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
84d0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
84e0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
84f0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
8500: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
8510: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
8520: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
8530: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
8540: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
8550: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
8560: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
8570: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
8580: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
8590: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
85a0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
85b0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
85c0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
85d0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
85e0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
85f0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8600: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8610: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8620: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8630: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8640: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8650: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8660: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8670: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8680: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8690: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
86a0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
86b0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
86c0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
86d0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
86e0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
86f0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8700: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8710: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8720: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8730: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8740: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8750: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8760: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8770: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8780: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8790: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
87a0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
87b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
87c0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
87d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
87e0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
87f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8800: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8810: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8820: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8830: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8840: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8850: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8860: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8870: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8880: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8890: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
88a0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
88b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
88c0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
88d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
88e0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
88f0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a  LE_WHEN_OPEN].**
8900: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8910: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
8920: 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e  ERWRITE].** <li>
8930: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
8940: 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69  MMUTABLE].** <li
8950: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8960: 42 41 54 43 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  BATCH_ATOMIC].**
8970: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
8980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8990: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
89a0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
89b0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
89c0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
89d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
89e0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
89f0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8a00: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8a10: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8a20: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8a30: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8a40: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
8a50: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
8a60: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
8a70: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
8a80: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8a90: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
8aa0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
8ab0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
8ac0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8ad0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8ae0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8af0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8b00: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8b10: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8b20: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8b30: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8b40: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
8b50: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
8b60: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
8b70: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
8b80: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
8b90: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
8ba0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
8bb0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
8bc0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8bd0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8be0: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8bf0: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8c00: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8c10: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8c20: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8c30: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8c40: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8c50: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
8c60: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
8c70: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
8c80: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
8c90: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
8ca0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
8cb0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
8cc0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8cd0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8ce0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8cf0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8d00: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8d10: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8d20: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8d30: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8d40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8d50: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
8d60: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
8d70: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8d80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8d90: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
8da0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
8db0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
8dc0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8dd0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8de0: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8df0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8e00: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8e10: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8e20: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8e30: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8e40: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
8e50: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8e60: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8e70: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
8e80: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
8e90: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8ea0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
8eb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ec0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8ed0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8ee0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ef0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8f00: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8f10: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8f20: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8f30: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8f40: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
8f50: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8f60: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
8f70: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
8f80: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8f90: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8fa0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8fb0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8fc0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8fd0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8fe0: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8ff0: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
9000: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
9010: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
9020: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
9030: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
9040: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
9050: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
9060: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
9070: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
9080: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
9090: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
90a0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
90b0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
90c0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
90d0: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
90e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
90f0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
9100: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
9110: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
9120: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
9130: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
9140: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
9150: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
9160: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
9170: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
9180: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
9190: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
91a0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
91b0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
91c0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
91d0: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
91e0: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
91f0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
9200: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
9210: 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74  odes} {file cont
9220: 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a  rol opcode}.**.*
9230: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
9240: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
9250: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
9260: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
9270: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
9280: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
9290: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
92a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
92b0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
92c0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
92d0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53   <ul>.** <li>[[S
92e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
92f0: 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  STATE]].** The [
9300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
9310: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
9320: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
9330: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
9340: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
9350: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
9360: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
9370: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
9380: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
9390: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
93a0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
93b0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
93c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
93d0: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
93e0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
93f0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
9400: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
9410: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
9420: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
9430: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9440: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
9450: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
9460: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
9470: 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  d is only availa
9480: 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c  ble when the SQL
9490: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70  ITE_TEST.** comp
94a0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
94b0: 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
94c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
94d0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a  L_SIZE_HINT]].**
94e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
94f0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70  TL_SIZE_HINT] op
9500: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
9510: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74  SQLite to give t
9520: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20  he VFS.** layer 
9530: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61  a hint of how la
9540: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  rge the database
9550: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20   file will grow 
9560: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65  to be during the
9570: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e  .** current tran
9580: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68  saction.  This h
9590: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61  int is not guara
95a0: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75  nteed to be accu
95b0: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69  rate but it.** i
95c0: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20  s often close.  
95d0: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56  The underlying V
95e0: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20  FS might choose 
95f0: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64  to preallocate d
9600: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
9610: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74  space based on t
9620: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65  his hint in orde
9630: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73  r to help writes
9640: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9650: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73  .** file run fas
9660: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
9670: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
9680: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
9690: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
96a0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
96b0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
96c0: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
96d0: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
96e0: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
96f0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
9700: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
9710: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
9720: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
9730: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
9740: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
9750: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
9760: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
9770: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
9780: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
9790: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
97a0: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
97b0: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
97c0: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
97d0: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
97e0: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
97f0: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
9800: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
9810: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
9820: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
9830: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
9840: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
9850: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
9860: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9870: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9880: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
9890: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
98a0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
98b0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
98c0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
98d0: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
98e0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
98f0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9900: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9910: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9920: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
9930: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
9940: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  RNAL_POINTER]..*
9950: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9960: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9970: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
9980: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9990: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20  OURNAL_POINTER] 
99a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
99b0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
99c0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
99d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
99e0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
99f0: 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66  th the journal f
9a00: 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74  ile (either.** t
9a10: 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75  he [rollback jou
9a20: 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72  rnal] or the [wr
9a30: 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20  ite-ahead log]) 
9a40: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
9a50: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9a60: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c  nection.  See al
9a70: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  so [SQLITE_FCNTL
9a80: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a  _FILE_POINTER]..
9a90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9aa0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
9ab0: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
9ac0: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9ad0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9ae0: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
9af0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9b00: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
9b10: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9b20: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9b30: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
9b40: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
9b50: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
9b60: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
9b70: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
9b80: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
9b90: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
9ba0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9bb0: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
9bc0: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9bd0: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9be0: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
9bf0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
9c00: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
9c10: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
9c20: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
9c30: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
9c40: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9c50: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
9c60: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
9c70: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
9c80: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
9c90: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
9ca0: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
9cb0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
9cc0: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9cd0: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
9ce0: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
9cf0: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
9d00: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
9d10: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
9d20: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
9d30: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
9d40: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
9d50: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
9d60: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
9d70: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9d80: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
9d90: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9da0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9db0: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
9dc0: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9dd0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9de0: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9df0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9e00: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
9e10: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
9e20: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9e30: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9e40: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9e50: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9e60: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
9e70: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
9e80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9e90: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
9ea0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9eb0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
9ec0: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
9ed0: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
9ee0: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
9ef0: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
9f00: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
9f10: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
9f20: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
9f30: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
9f40: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
9f50: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
9f60: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9f70: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9f80: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
9f90: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
9fa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9fb0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9fc0: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9fd0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9fe0: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
9ff0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
a000: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
a010: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
a020: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
a030: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
a040: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
a050: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a060: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
a070: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
a080: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
a090: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
a0a0: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
a0b0: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
a0c0: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
a0d0: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
a0e0: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
a0f0: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
a100: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
a110: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
a120: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
a130: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
a140: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
a150: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
a160: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
a170: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
a180: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
a190: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
a1a0: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
a1b0: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
a1c0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
a1d0: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
a1e0: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
a1f0: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
a200: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
a210: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
a220: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
a230: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
a240: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
a250: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
a260: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
a270: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
a280: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
a290: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
a2a0: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
a2b0: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
a2c0: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
a2d0: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
a2e0: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
a2f0: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
a300: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
a310: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
a320: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
a330: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
a340: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
a350: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
a360: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
a370: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
a380: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
a390: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
a3a0: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
a3b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
a3c0: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
a3d0: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
a3e0: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
a3f0: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
a400: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
a410: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
a420: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
a430: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
a440: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
a450: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
a460: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
a470: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
a480: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a490: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
a4a0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a4b0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
a4c0: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
a4d0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
a4e0: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
a4f0: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
a500: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
a510: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
a520: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
a530: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
a540: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
a550: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
a560: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
a570: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
a580: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
a590: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
a5a0: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
a5b0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
a5c0: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
a5d0: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
a5e0: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
a5f0: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
a600: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
a610: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
a620: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
a630: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
a640: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
a650: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
a660: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
a670: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
a680: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
a690: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
a6a0: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
a6b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
a6c0: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
a6d0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
a6e0: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
a6f0: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
a700: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
a710: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
a720: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a730: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a740: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a750: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
a760: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
a770: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
a780: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
a790: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
a7a0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
a7b0: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
a7c0: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
a7d0: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
a7e0: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
a7f0: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
a800: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
a810: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
a820: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
a830: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a840: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a850: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
a860: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
a870: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a880: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a890: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
a8a0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
a8b0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
a8c0: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
a8d0: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
a8e0: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
a8f0: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
a900: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
a910: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
a920: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a930: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
a940: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
a950: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
a960: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
a970: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a980: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a990: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a9a0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a9b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a9c0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a9d0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a9e0: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
a9f0: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
aa00: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
aa10: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
aa20: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
aa30: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
aa40: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
aa50: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
aa60: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
aa70: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
aa80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
aa90: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
aaa0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
aab0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
aac0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
aad0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
aae0: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
aaf0: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
ab00: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
ab10: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
ab20: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
ab30: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
ab40: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
ab50: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
ab60: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
ab70: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
ab80: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
ab90: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
aba0: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
abb0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
abc0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
abd0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
abe0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
abf0: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
ac00: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
ac10: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
ac20: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
ac30: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
ac40: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
ac50: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
ac60: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
ac70: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
ac80: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
ac90: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
aca0: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
acb0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
acc0: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
acd0: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
ace0: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
acf0: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
ad00: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
ad10: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
ad20: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
ad30: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
ad40: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
ad50: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
ad60: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
ad70: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
ad80: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
ad90: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
ada0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
adb0: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
adc0: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
add0: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
ade0: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
adf0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
ae00: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
ae10: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
ae20: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
ae30: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
ae40: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
ae50: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
ae60: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
ae70: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
ae80: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ae90: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
aea0: 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TER]].** ^The [S
aeb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
aec0: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
aed0: 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20  finds a pointer 
aee0: 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c  to the top-level
aef0: 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72  .** [VFSes] curr
af00: 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e  ently in use.  ^
af10: 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20  (The argument X 
af20: 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  in.** sqlite3_fi
af30: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51  le_control(db,SQ
af40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
af50: 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62  OINTER,X) must b
af60: 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73  e.** of type "[s
af70: 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e  qlite3_vfs] **".
af80: 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77    This opcodes w
af90: 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f  ill set *X.** to
afa0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
afb0: 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e  e top-level VFS.
afc0: 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72  )^.** ^When ther
afd0: 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56  e are multiple V
afe0: 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20  FS shims in the 
aff0: 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f  stack, this opco
b000: 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20  de finds the.** 
b010: 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20  upper-most shim 
b020: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
b030: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
b040: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
b050: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
b060: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
b070: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
b080: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
b090: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
b0a0: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
b0b0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
b0c0: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
b0d0: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
b0e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
b0f0: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
b100: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
b110: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
b120: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
b130: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b140: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b150: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
b160: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
b170: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
b180: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
b190: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
b1a0: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
b1b0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
b1c0: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
b1d0: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
b1e0: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
b1f0: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
b200: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
b210: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
b220: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
b230: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
b240: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b250: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
b260: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
b270: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
b280: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
b290: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
b2a0: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
b2b0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
b2c0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
b2d0: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
b2e0: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
b2f0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
b300: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
b310: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
b320: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
b330: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
b340: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
b350: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
b360: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
b370: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
b380: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
b390: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
b3a0: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
b3b0: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
b3c0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
b3d0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b3e0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b3f0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
b400: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
b410: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
b420: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
b430: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
b440: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
b450: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
b460: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
b470: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
b480: 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69  t if result stri
b490: 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74  ng is NULL, or t
b4a0: 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f  hat returns a co
b4b0: 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  py.** of the res
b4c0: 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68  ult string if th
b4d0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d  e string is non-
b4e0: 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  NULL..** ^If the
b4f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b500: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b510: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  rol returns.** a
b520: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f  ny result code o
b530: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
b540: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45  E_OK] or [SQLITE
b550: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74  _NOTFOUND], that
b560: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74   means.** that t
b570: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72  he VFS encounter
b580: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c  ed an error whil
b590: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b  e handling the [
b5a0: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a  PRAGMA] and the.
b5b0: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f  ** compilation o
b5c0: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69  f the PRAGMA fai
b5d0: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ls with an error
b5e0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
b5f0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
b600: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63   file control oc
b610: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69  curs at the begi
b620: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20  nning of pragma 
b630: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73  statement analys
b640: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20  is and so.** it 
b650: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72  is able to overr
b660: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52  ide built-in [PR
b670: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
b680: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b690: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b6a0: 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  ANDLER]].** ^The
b6b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
b6c0: 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66  USYHANDLER].** f
b6d0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20  ile-control may 
b6e0: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  be invoked by SQ
b6f0: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61  Lite on the data
b700: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  base file handle
b710: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65  .** shortly afte
b720: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69  r it is opened i
b730: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
b740: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20  de a custom VFS 
b750: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74  with access.** t
b760: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  o the connection
b770: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63  s busy-handler c
b780: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67  allback. The arg
b790: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65  ument is of type
b7a0: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20   (void **).** - 
b7b0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20  an array of two 
b7c0: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e  (void *) values.
b7d0: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64   The first (void
b7e0: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69   *) actually poi
b7f0: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63  nts.** to a func
b800: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e  tion of type (in
b810: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20  t (*)(void *)). 
b820: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f  In order to invo
b830: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ke the connectio
b840: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c  ns.** busy-handl
b850: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  er, this functio
b860: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f  n should be invo
b870: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63  ked with the sec
b880: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a  ond (void *) in.
b890: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20  ** the array as 
b8a0: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  the only argumen
b8b0: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  t. If it returns
b8c0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
b8d0: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
b8e0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69   should be retri
b8f0: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  ed. If it return
b900: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74  s zero, the cust
b910: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62  om VFS should ab
b920: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72  andon the.** cur
b930: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a  rent operation..
b940: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b950: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b960: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c  ENAME]].** ^Appl
b970: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f  ication can invo
b980: 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  ke the [SQLITE_F
b990: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
b9a0: 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  E] file-control.
b9b0: 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74  ** to have SQLit
b9c0: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20  e generate a.** 
b9d0: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
b9e0: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  me using the sam
b9f0: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74  e algorithm that
ba00: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20   is followed to 
ba10: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70  generate.** temp
ba20: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20  orary filenames 
ba30: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20  for TEMP tables 
ba40: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e  and other intern
ba50: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a  al uses.  The.**
ba60: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
ba70: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69   be a char** whi
ba80: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65  ch will be fille
ba90: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e  d with the filen
baa0: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69  ame.** written i
bab0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
bac0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
bad0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
bae0: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a  e caller should.
baf0: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ** invoke [sqlit
bb00: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68  e3_free()] on th
bb10: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69  e result to avoi
bb20: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e  d a memory leak.
bb30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bb40: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
bb50: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
bb60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
bb70: 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
bb80: 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75  ol is used to qu
bb90: 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a  ery or set the.*
bba0: 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  * maximum number
bbb0: 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77   of bytes that w
bbc0: 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20  ill be used for 
bbd0: 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f  memory-mapped I/
bbe0: 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  O..** The argume
bbf0: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
bc00: 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79  to a value of ty
bc10: 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  pe sqlite3_int64
bc20: 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61   that.** is an a
bc30: 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20  dvisory maximum 
bc40: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
bc50: 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d  in the file to m
bc60: 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a  emory map.  The.
bc70: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76  ** pointer is ov
bc80: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
bc90: 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54  he old value.  T
bca0: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  he limit is not 
bcb0: 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68  changed if.** th
bcc0: 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c  e value original
bcd0: 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73  ly pointed to is
bce0: 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73   negative, and s
bcf0: 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69  o the current li
bd00: 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71  mit .** can be q
bd10: 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e  ueried by passin
bd20: 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  g in a pointer t
bd30: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  o a negative num
bd40: 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69  ber.  This.** fi
bd50: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le-control is us
bd60: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
bd70: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47   implement [PRAG
bd80: 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a  MA mmap_size]..*
bd90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bda0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a  E_FCNTL_TRACE]].
bdb0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bdc0: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65  CNTL_TRACE] file
bdd0: 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65   control provide
bde0: 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72  s advisory infor
bdf0: 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65  mation.** to the
be00: 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20   VFS about what 
be10: 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72  the higher layer
be20: 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  s of the SQLite 
be30: 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e  stack are doing.
be40: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f  .** This file co
be50: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79  ntrol is used by
be60: 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69   some VFS activi
be70: 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d  ty tracing [shim
be80: 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  s]..** The argum
be90: 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65  ent is a zero-te
bea0: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e  rminated string.
beb0: 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20    Higher layers 
bec0: 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  in the.** SQLite
bed0: 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72   stack may gener
bee0: 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66  ate instances of
bef0: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
bf00: 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51  ol if.** the [SQ
bf10: 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54  LITE_USE_FCNTL_T
bf20: 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
bf30: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
bf40: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  bled..**.** <li>
bf50: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  [[SQLITE_FCNTL_H
bf60: 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68  AS_MOVED]].** Th
bf70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bf80: 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20  HAS_MOVED] file 
bf90: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
bfa0: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
bfb0: 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  as a.** pointer 
bfc0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
bfd0: 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f  d it writes a bo
bfe0: 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20  olean into that 
bff0: 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e  integer dependin
c000: 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  g.** on whether 
c010: 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20  or not the file 
c020: 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64  has been renamed
c030: 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65  , moved, or dele
c040: 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20  ted since it.** 
c050: 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64  was first opened
c060: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c070: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c080: 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a  _GET_HANDLE]].**
c090: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c0a0: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
c0b0: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  DLE] opcode can 
c0c0: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
c0d0: 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  n the.** underly
c0e0: 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20  ing native file 
c0f0: 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65  handle associate
c100: 64 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61  d with a file ha
c110: 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65  ndle.  This file
c120: 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65  .** control inte
c130: 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d  rprets its argum
c140: 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72  ent as a pointer
c150: 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c   to a native fil
c160: 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20  e handle and.** 
c170: 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c  writes the resul
c180: 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65  ting value there
c190: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c1b0: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a  _SET_HANDLE]].**
c1c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c1d0: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
c1e0: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  DLE] opcode is u
c1f0: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
c200: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
c210: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
c220: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
c230: 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69  d to swap the fi
c240: 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74  le handle with t
c250: 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65  he one.** pointe
c260: 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67  d to by the pArg
c270: 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73   argument.  This
c280: 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75   capability is u
c290: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
c2a0: 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e  ng.** and only n
c2b0: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
c2c0: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
c2d0: 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64  _TEST is defined
c2e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c300: 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  LOCK]].** The [S
c310: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
c320: 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e  BLOCK] is a sign
c330: 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61  al to the VFS la
c340: 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68  yer that it migh
c350: 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67  t.** be advantag
c360: 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e  eous to block on
c370: 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f   the next WAL lo
c380: 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69  ck if the lock i
c390: 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c  s not immediatel
c3a0: 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20  y.** available. 
c3b0: 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74   The WAL subsyst
c3c0: 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73  em issues this s
c3d0: 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72  ignal during rar
c3e0: 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63  e.** circumstanc
c3f0: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  es in order to f
c400: 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74  ix a problem wit
c410: 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72  h priority inver
c420: 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  sion..** Applica
c430: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d  tions should <em
c440: 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68  >not</em> use th
c450: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e  is file-control.
c460: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c470: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c480: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c490: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20  E_FCNTL_ZIPVFS] 
c4a0: 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d  opcode is implem
c4b0: 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20  ented by zipvfs 
c4c0: 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a  only. All other.
c4d0: 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  ** VFS should re
c4e0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
c4f0: 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70  OUND for this op
c500: 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  code..**.** <li>
c510: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  [[SQLITE_FCNTL_R
c520: 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  BU]].** The [SQL
c530: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f  ITE_FCNTL_RBU] o
c540: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
c550: 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63  nted by the spec
c560: 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a  ial VFS used by.
c570: 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e  ** the RBU exten
c580: 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20  sion only.  All 
c590: 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64  other VFS should
c5a0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
c5b0: 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74  OTFOUND for.** t
c5c0: 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a  his opcode.  .**
c5d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c5e0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c5f0: 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49  MIC_WRITE]].** I
c600: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
c610: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
c620: 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72  _WRITE] opcode r
c630: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
c640: 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69  , then.** the fi
c650: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 69 73  le descriptor is
c660: 20 70 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63   placed in "batc
c670: 68 20 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77  h write mode", w
c680: 68 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c  hich.** means al
c690: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69  l subsequent wri
c6a0: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69  te operations wi
c6b0: 6c 6c 20 62 65 20 64 65 66 65 72 72 65 64 20 61  ll be deferred a
c6c0: 6e 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69  nd done.** atomi
c6d0: 63 61 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78  cally at the nex
c6e0: 74 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  t [SQLITE_FCNTL_
c6f0: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
c700: 49 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a  ITE].  Systems.*
c710: 2a 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75  * that do not su
c720: 70 70 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d  pport batch atom
c730: 69 63 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72  ic writes will r
c740: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54  eturn SQLITE_NOT
c750: 46 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f  FOUND..** ^Follo
c760: 77 69 6e 67 20 61 20 73 75 63 63 65 73 73 66 75  wing a successfu
c770: 6c 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  l SQLITE_FCNTL_B
c780: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c790: 45 20 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a  E and prior to.*
c7a0: 2a 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53  * the closing [S
c7b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c7c0: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IT_ATOMIC_WRITE]
c7d0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   or.** [SQLITE_F
c7e0: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
c7f0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c  OMIC_WRITE], SQL
c800: 69 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a  ite will make.**
c810: 20 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63   no VFS interfac
c820: 65 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73  e calls on the s
c830: 61 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  ame [sqlite3_fil
c840: 65 5d 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  e] file descript
c850: 6f 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72  or.** except for
c860: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57   calls to the xW
c870: 72 69 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20  rite method and 
c880: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
c890: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20   method.** with 
c8a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
c8b0: 5a 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20  ZE_HINT]..**.** 
c8c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c8d0: 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  TL_COMMIT_ATOMIC
c8e0: 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20  _WRITE]].** The 
c8f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c900: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c910: 45 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  E] opcode causes
c920: 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70   all write.** op
c930: 65 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74  erations since t
c940: 68 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63  he previous succ
c950: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a  essful call to .
c960: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
c970: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c980: 49 54 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f  ITE] to be perfo
c990: 72 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e  rmed atomically.
c9a0: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f  .** This file co
c9b0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
c9c0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64  QLITE_OK] if and
c9d0: 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69   only if the wri
c9e0: 74 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20  tes were.** all 
c9f0: 70 65 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73  performed succes
ca00: 73 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20  sfully and have 
ca10: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74  been committed t
ca20: 6f 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f  o persistent sto
ca30: 72 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64  rage..** ^Regard
ca40: 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
ca50: 6f 72 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63  or not it is suc
ca60: 63 65 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69  cessful, this fi
ca70: 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73  le control takes
ca80: 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73  .** the file des
ca90: 63 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62  criptor out of b
caa0: 61 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20  atch write mode 
cab0: 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73  so that all subs
cac0: 65 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20  equent.** write 
cad0: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69  operations are i
cae0: 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e  ndependent..** ^
caf0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
cb00: 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f  r invoke SQLITE_
cb10: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
cb20: 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75  MIC_WRITE withou
cb30: 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63  t.** a prior suc
cb40: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
cb50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
cb60: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
cb70: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
cb80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c  QLITE_FCNTL_ROLL
cb90: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54  BACK_ATOMIC_WRIT
cba0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
cbb0: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
cbc0: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  K_ATOMIC_WRITE] 
cbd0: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c  opcode causes al
cbe0: 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61  l write.** opera
cbf0: 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20  tions since the 
cc00: 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73  previous success
cc10: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20  ful call to .** 
cc20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
cc30: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
cc40: 5d 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62  ] to be rolled b
cc50: 61 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69  ack..** ^This fi
cc60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73  le control takes
cc70: 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69   the file descri
cc80: 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63  ptor out of batc
cc90: 68 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20  h write mode.** 
cca0: 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73  so that all subs
ccb0: 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65  equent write ope
ccc0: 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65  rations are inde
ccd0: 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c  pendent..** ^SQL
cce0: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
ccf0: 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e  nvoke SQLITE_FCN
cd00: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
cd10: 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74  IC_WRITE without
cd20: 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63  .** a prior succ
cd30: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
cd40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
cd50: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
cd60: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
cd70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f  LITE_FCNTL_LOCK_
cd80: 54 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65  TIMEOUT]].** The
cd90: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
cda0: 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63  OCK_TIMEOUT] opc
cdb0: 6f 64 65 20 63 61 75 73 65 73 20 61 74 74 65 6d  ode causes attem
cdc0: 70 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  pts to obtain.**
cdd0: 20 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69   a file lock usi
cde0: 6e 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20  ng the xLock or 
cdf0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73  xShmLock methods
ce00: 20 6f 66 20 74 68 65 20 56 46 53 20 74 6f 20 77   of the VFS to w
ce10: 61 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f  ait.** for up to
ce20: 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20   M milliseconds 
ce30: 62 65 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20  before failing, 
ce40: 77 68 65 72 65 20 4d 20 69 73 20 74 68 65 20 73  where M is the s
ce50: 69 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e  ingle .** unsign
ce60: 65 64 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d  ed integer param
ce70: 65 74 65 72 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  eter..** </ul>.*
ce80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ce90: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
cea0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
ceb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cec0: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
ced0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a  OXYFILE       2.
cee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cef0: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
cf00: 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23  XYFILE       3.#
cf10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cf20: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  NTL_LAST_ERRNO  
cf30: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
cf40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cf50: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
cf60: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
cf70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cf80: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
cf90: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
cfa0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cfb0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
cfc0: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
cfd0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cfe0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
cff0: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
d000: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
d010: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
d020: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
d030: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
d040: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
d050: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
d060: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
d070: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
d080: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
d090: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
d0a0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
d0b0: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
d0c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
d0d0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
d0e0: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
d0f0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
d100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d110: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
d120: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
d130: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
d140: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
d150: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
d160: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
d170: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
d180: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
d190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
d1a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d1b0: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20  FCNTL_TRACE     
d1c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a               19.
d1d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d1e0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20  CNTL_HAS_MOVED  
d1f0: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23              20.#
d200: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d210: 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20  NTL_SYNC        
d220: 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64             21.#d
d230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d240: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
d250: 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65  WO        22.#de
d260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d270: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
d280: 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66  LE       23.#def
d290: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d2a0: 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20  _WAL_BLOCK      
d2b0: 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69          24.#defi
d2c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d2d0: 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20  ZIPVFS          
d2e0: 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e         25.#defin
d2f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  e SQLITE_FCNTL_R
d300: 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20  BU              
d310: 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65        26.#define
d320: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
d330: 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  S_POINTER       
d340: 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20       27.#define 
d350: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
d360: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20  RNAL_POINTER    
d370: 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53      28.#define S
d380: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d390: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_GET_HANDLE    
d3a0: 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51     29.#define SQ
d3b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20  LITE_FCNTL_PDB  
d3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d3d0: 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    30.#define SQL
d3e0: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
d3f0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
d400: 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   31.#define SQLI
d410: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
d420: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
d430: 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  32.#define SQLIT
d440: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
d450: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 33  _ATOMIC_WRITE  3
d460: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
d470: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45  _FCNTL_LOCK_TIME
d480: 4f 55 54 20 20 20 20 20 20 20 20 20 20 20 33 34  OUT           34
d490: 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20  ../* deprecated 
d4a0: 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  names */.#define
d4b0: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
d4c0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
d4d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
d4e0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
d4f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
d500: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
d510: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
d520: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
d530: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
d540: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
d550: 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f           SQLITE_
d560: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
d570: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
d580: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
d590: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
d5a0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
d5b0: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
d5c0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
d5d0: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
d5e0: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
d5f0: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
d600: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
d610: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
d620: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
d630: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
d640: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
d650: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
d660: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
d670: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
d680: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
d690: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
d6a0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
d6b0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
d6c0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
d6d0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
d6e0: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
d6f0: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
d700: 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c  API3REF: Loadabl
d710: 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e  e Extension Thun
d720: 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  k.**.** A pointe
d730: 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20  r to the opaque 
d740: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
d750: 69 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69  ines structure i
d760: 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  s passed as.** t
d770: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
d780: 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e  er to entry poin
d790: 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20  ts of [loadable 
d7a0: 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68  extensions].  Th
d7b0: 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  is.** structure 
d7c0: 6d 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65  must be typedefe
d7d0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f  d in order to wo
d7e0: 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c  rk around compil
d7f0: 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f  er warnings.** o
d800: 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73  n some platforms
d810: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
d820: 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
d830: 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33  routines sqlite3
d840: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a  _api_routines;..
d850: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d860: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
d870: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
d880: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
d890: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
d8a0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
d8b0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
d8c0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
d8d0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
d8e0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
d8f0: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
d900: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
d910: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
d920: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
d930: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
d940: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
d950: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
d960: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
d970: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
d980: 2a 0a 2a 2a 20 54 68 65 20 56 46 53 20 69 6e 74  *.** The VFS int
d990: 65 72 66 61 63 65 20 69 73 20 73 6f 6d 65 74 69  erface is someti
d9a0: 6d 65 73 20 65 78 74 65 6e 64 65 64 20 62 79 20  mes extended by 
d9b0: 61 64 64 69 6e 67 20 6e 65 77 20 6d 65 74 68 6f  adding new metho
d9c0: 64 73 20 6f 6e 74 6f 0a 2a 2a 20 74 68 65 20 65  ds onto.** the e
d9d0: 6e 64 2e 20 20 45 61 63 68 20 74 69 6d 65 20 73  nd.  Each time s
d9e0: 75 63 68 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e  uch an extension
d9f0: 20 6f 63 63 75 72 73 2c 20 74 68 65 20 69 56 65   occurs, the iVe
da00: 72 73 69 6f 6e 20 66 69 65 6c 64 0a 2a 2a 20 69  rsion field.** i
da10: 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 20 20  s incremented.  
da20: 54 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  The iVersion val
da30: 75 65 20 73 74 61 72 74 65 64 20 6f 75 74 20 61  ue started out a
da40: 73 20 31 20 69 6e 0a 2a 2a 20 53 51 4c 69 74 65  s 1 in.** SQLite
da50: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 5d   [version 3.5.0]
da60: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 35 2e   on [dateof:3.5.
da70: 30 5d 2c 20 74 68 65 6e 20 69 6e 63 72 65 61 73  0], then increas
da80: 65 64 20 74 6f 20 32 0a 2a 2a 20 77 69 74 68 20  ed to 2.** with 
da90: 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20  SQLite [version 
daa0: 33 2e 37 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f  3.7.0] on [dateo
dab0: 66 3a 33 2e 37 2e 30 5d 2c 20 61 6e 64 20 74 68  f:3.7.0], and th
dac0: 65 6e 20 69 6e 63 72 65 61 73 65 64 0a 2a 2a 20  en increased.** 
dad0: 74 6f 20 33 20 77 69 74 68 20 53 51 4c 69 74 65  to 3 with SQLite
dae0: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 36 5d   [version 3.7.6]
daf0: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e   on [dateof:3.7.
db00: 36 5d 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  6].  Additional 
db10: 66 69 65 6c 64 73 0a 2a 2a 20 6d 61 79 20 62 65  fields.** may be
db20: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65   appended to the
db30: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
db40: 65 63 74 20 61 6e 64 20 74 68 65 20 69 56 65 72  ect and the iVer
db50: 73 69 6f 6e 20 76 61 6c 75 65 0a 2a 2a 20 6d 61  sion value.** ma
db60: 79 20 69 6e 63 72 65 61 73 65 20 61 67 61 69 6e  y increase again
db70: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
db80: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
db90: 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
dba0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
dbb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
dbc0: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
dbd0: 6e 20 74 68 65 20 74 72 61 6e 73 69 74 69 6f 6e  n the transition
dbe0: 20 66 72 6f 6d 0a 2a 2a 20 53 51 4c 69 74 65 20   from.** SQLite 
dbf0: 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 5d 20  [version 3.5.9] 
dc00: 74 6f 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e  to [version 3.6.
dc10: 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e  0] on [dateof:3.
dc20: 36 2e 30 5d 0a 2a 2a 20 61 6e 64 20 79 65 74 20  6.0].** and yet 
dc30: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
dc40: 6c 64 20 77 61 73 20 6e 6f 74 20 6d 6f 64 69 66  ld was not modif
dc50: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
dc60: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
dc70: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
dc80: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
dc90: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
dca0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
dcb0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
dcc0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
dcd0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
dce0: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
dcf0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
dd00: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
dd10: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
dd20: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
dd30: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
dd40: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
dd50: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
dd60: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
dd70: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
dd80: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
dd90: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
dda0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
ddb0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
ddc0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
ddd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
dde0: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
ddf0: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
de00: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
de10: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
de20: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
de30: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
de40: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
de50: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
de60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
de70: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
de80: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
de90: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
dea0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
deb0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
dec0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
ded0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
dee0: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
def0: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
df00: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
df10: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
df20: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
df30: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
df40: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
df50: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
df60: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
df70: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
df80: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
df90: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
dfa0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
dfb0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
dfc0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
dfd0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
dfe0: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
dff0: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
e000: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
e010: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
e020: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
e030: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
e040: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e050: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
e060: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
e070: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
e080: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
e090: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
e0a0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
e0b0: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
e0c0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
e0d0: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
e0e0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
e0f0: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
e100: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
e110: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
e120: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
e130: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
e140: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
e150: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
e160: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
e170: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
e180: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
e190: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
e1a0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
e1b0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
e1c0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
e1d0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
e1e0: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
e1f0: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
e200: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
e210: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
e220: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
e230: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
e240: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
e250: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
e260: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
e270: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
e280: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
e290: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
e2a0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
e2b0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
e2c0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
e2d0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
e2e0: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
e2f0: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
e300: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
e310: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
e320: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
e330: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
e340: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
e350: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
e360: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e370: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
e380: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
e390: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
e3a0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
e3b0: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
e3c0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
e3d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
e3e0: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
e3f0: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
e400: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
e410: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
e420: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
e430: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
e440: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
e450: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
e460: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
e470: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
e480: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
e490: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
e4a0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
e4b0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
e4c0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
e4d0: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
e4e0: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
e4f0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
e500: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
e510: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
e520: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
e530: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
e540: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
e550: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
e560: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
e570: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
e580: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
e590: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e5a0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
e5b0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
e5c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
e5d0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
e5e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
e5f0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
e600: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
e610: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
e620: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e630: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
e640: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e650: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
e660: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
e670: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
e680: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
e690: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
e6a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
e6b0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
e6c0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
e6d0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
e6e0: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
e6f0: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
e700: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
e710: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
e720: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
e730: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
e740: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
e750: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
e760: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
e770: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
e780: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
e790: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
e7a0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
e7b0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
e7c0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
e7d0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
e7e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
e7f0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
e800: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
e810: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
e820: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
e830: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
e840: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
e850: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
e860: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
e870: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
e880: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
e890: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
e8a0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
e8b0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
e8c0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
e8d0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
e8e0: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
e8f0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
e900: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
e910: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
e920: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
e930: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
e940: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
e950: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
e960: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
e970: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
e980: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
e990: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
e9a0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
e9b0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
e9c0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
e9d0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
e9e0: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
e9f0: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
ea00: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
ea10: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
ea20: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
ea30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
ea40: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
ea50: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
ea60: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
ea70: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
ea80: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
ea90: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
eaa0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
eab0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
eac0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
ead0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
eae0: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
eaf0: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
eb00: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
eb10: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
eb20: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
eb30: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
eb40: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
eb50: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
eb60: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
eb70: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
eb80: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
eb90: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
eba0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
ebb0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
ebc0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
ebd0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
ebe0: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
ebf0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
ec00: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
ec10: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
ec20: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
ec30: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
ec40: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
ec50: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
ec60: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
ec70: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
ec80: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
ec90: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
eca0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
ecb0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
ecc0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
ecd0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
ece0: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
ecf0: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
ed00: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
ed10: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
ed20: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
ed30: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
ed40: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
ed50: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
ed60: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
ed70: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
ed80: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
ed90: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
eda0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
edb0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
edc0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
edd0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
ede0: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
edf0: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
ee00: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
ee10: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
ee20: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
ee30: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
ee40: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
ee50: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
ee60: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
ee70: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
ee80: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ee90: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
eea0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
eeb0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
eec0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
eed0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
eee0: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
eef0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
ef00: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
ef10: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
ef20: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
ef30: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
ef40: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
ef50: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
ef60: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
ef70: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
ef80: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
ef90: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
efa0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
efb0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
efc0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
efd0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
efe0: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
eff0: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
f000: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
f010: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
f020: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
f030: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
f040: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
f050: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
f060: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
f070: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
f080: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
f090: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
f0a0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
f0b0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
f0c0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
f0d0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
f0e0: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
f0f0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
f100: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
f110: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
f120: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
f130: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
f140: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
f150: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
f160: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
f170: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
f180: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
f190: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
f1a0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
f1b0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
f1c0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
f1d0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
f1e0: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
f1f0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
f200: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
f210: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
f220: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
f230: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
f240: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
f250: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
f260: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
f270: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
f280: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
f290: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
f2a0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
f2b0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
f2c0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
f2d0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
f2e0: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
f2f0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
f300: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
f310: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
f320: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
f330: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
f340: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
f350: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
f360: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
f370: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
f380: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
f390: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f3a0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
f3b0: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
f3c0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
f3d0: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
f3e0: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
f3f0: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
f400: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
f410: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
f420: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
f430: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
f440: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f450: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
f460: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
f470: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
f480: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
f490: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
f4a0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
f4b0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
f4c0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
f4d0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
f4e0: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
f4f0: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
f500: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
f510: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
f520: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
f530: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
f540: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
f550: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
f560: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
f570: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
f580: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
f590: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
f5a0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
f5b0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
f5c0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
f5d0: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
f5e0: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
f5f0: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
f600: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
f610: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
f620: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
f630: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
f640: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
f650: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
f660: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
f670: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
f680: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
f690: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
f6a0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
f6b0: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
f6c0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
f6d0: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
f6e0: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
f6f0: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
f700: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
f710: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
f720: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
f730: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
f740: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
f750: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
f760: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
f770: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
f780: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
f790: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
f7a0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
f7b0: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
f7c0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
f7d0: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
f7e0: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
f7f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
f800: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
f810: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
f820: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
f830: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
f840: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
f850: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
f860: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
f870: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
f880: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
f890: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
f8a0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
f8b0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
f8c0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
f8d0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
f8e0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
f8f0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
f900: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
f910: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
f920: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
f930: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
f940: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
f950: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
f960: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
f970: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
f980: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
f990: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
f9a0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
f9b0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
f9c0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
f9d0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
f9e0: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
f9f0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
fa00: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
fa10: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
fa20: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
fa30: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
fa40: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
fa50: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
fa60: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fa70: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
fa80: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
fa90: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
faa0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
fab0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
fac0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
fad0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
fae0: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
faf0: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
fb00: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
fb10: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
fb20: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
fb30: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
fb40: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
fb50: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
fb60: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
fb70: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
fb80: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
fb90: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
fba0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fbb0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
fbc0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
fbd0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
fbe0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
fbf0: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
fc00: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
fc10: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
fc20: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
fc30: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
fc40: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
fc50: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
fc60: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
fc70: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
fc80: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
fc90: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
fca0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
fcb0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
fcc0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
fcd0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
fce0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
fcf0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
fd00: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
fd10: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
fd20: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fd30: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
fd40: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
fd50: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
fd60: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
fd70: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
fd80: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
fd90: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
fda0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
fdb0: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
fdc0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
fdd0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
fde0: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
fdf0: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
fe00: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
fe10: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
fe20: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
fe30: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
fe40: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
fe50: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
fe60: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
fe70: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
fe80: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
fe90: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
fea0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
feb0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
fec0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
fed0: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
fee0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
fef0: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
ff00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ff10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ff20: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
ff30: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
ff40: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
ff50: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ff60: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
ff70: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
ff80: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
ff90: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
ffa0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
ffb0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
ffc0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
ffd0: 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72  ppended in futur
ffe0: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
fff0: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
10000 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
10010 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
10020 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
10030 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
10040 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
10050 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
10060 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
10070 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
10080 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
10090 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
100a0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
100b0 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
100c0 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
100d0 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
100e0 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
100f0 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
10100 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
10110 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
10120 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
10130 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
10140 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
10150 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
10160 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
10170 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
10180 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
10190 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
101a0 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
101b0 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
101c0 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
101d0 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
101e0 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
101f0 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
10200 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
10210 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
10220 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
10230 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
10240 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
10250 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
10260 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10270 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
10280 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
10290 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
102a0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
102b0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
102c0 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
102d0 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
102e0 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
102f0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
10300 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
10310 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
10320 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
10330 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
10340 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
10350 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
10360 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
10370 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
10380 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
10390 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
103a0 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
103b0 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
103c0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
103d0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
103e0 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
103f0 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10400 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
10410 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
10420 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
10430 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
10440 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10450 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
10460 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
10470 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
10480 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
10490 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
104a0 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
104b0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
104c0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
104d0 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
104e0 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
104f0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
10500 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
10510 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
10520 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
10530 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
10540 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
10550 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
10560 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
10570 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
10580 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
10590 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
105a0 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
105b0 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
105c0 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
105d0 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
105e0 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
105f0 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
10600 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
10610 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10620 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
10630 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
10640 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
10650 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
10660 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
10670 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
10680 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
10690 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
106a0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
106b0 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
106c0 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
106d0 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
106e0 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
106f0 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
10700 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
10710 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
10720 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
10730 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
10740 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
10750 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
10760 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
10770 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
10780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
10790 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
107a0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
107b0 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
107c0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
107d0 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
107e0 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
107f0 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
10800 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
10810 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
10820 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
10830 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
10840 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
10850 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
10860 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
10870 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
10880 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
10890 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
108a0 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
108b0 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
108c0 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
108d0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
108e0 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
108f0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
10900 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
10910 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
10920 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
10930 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
10940 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
10950 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
10960 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
10970 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
10980 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
10990 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
109a0 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
109b0 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
109c0 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
109d0 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
109e0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
109f0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
10a00 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
10a10 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
10a20 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
10a30 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
10a40 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
10a50 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
10a60 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
10a70 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
10a80 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
10a90 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
10aa0 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
10ab0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
10ac0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
10ad0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
10ae0 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
10af0 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
10b00 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
10b10 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10b20 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
10b30 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
10b40 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
10b50 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
10b60 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
10b70 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
10b80 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
10b90 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
10ba0 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
10bb0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
10bc0 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
10bd0 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
10be0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10bf0 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
10c00 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
10c10 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
10c20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
10c30 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
10c40 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
10c50 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
10c60 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
10c70 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
10c80 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
10c90 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10ca0 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
10cb0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10cc0 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
10cd0 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
10ce0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
10cf0 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
10d00 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
10d10 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
10d20 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
10d30 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10d40 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
10d50 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
10d60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
10d70 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
10d80 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
10d90 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
10da0 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
10db0 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
10dc0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
10dd0 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
10de0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
10df0 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
10e00 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
10e10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10e20 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
10e30 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
10e40 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
10e50 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
10e60 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
10e70 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
10e80 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10e90 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
10ea0 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
10eb0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10ec0 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
10ed0 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
10ee0 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
10ef0 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
10f00 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
10f10 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
10f20 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
10f30 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10f40 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
10f50 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
10f60 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
10f70 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
10f80 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
10f90 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
10fa0 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
10fb0 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
10fc0 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
10fd0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
10fe0 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
10ff0 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
11000 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
11010 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
11020 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
11030 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
11040 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
11050 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
11060 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
11070 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
11080 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
11090 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
110a0 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
110b0 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
110c0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
110d0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
110e0 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
110f0 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
11100 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
11110 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
11120 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11130 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
11140 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
11150 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
11160 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
11170 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
11180 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
11190 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
111a0 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
111b0 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
111c0 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
111d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
111e0 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
111f0 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
11200 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
11210 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
11220 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
11230 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11240 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
11250 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
11260 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
11270 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11280 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
11290 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
112a0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
112b0 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
112c0 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
112d0 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
112e0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
112f0 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
11300 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
11310 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
11320 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
11330 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
11340 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11350 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
11360 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
11370 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
11380 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
11390 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
113a0 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
113b0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
113c0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
113d0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
113e0 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
113f0 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
11400 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
11410 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
11420 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
11430 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11440 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
11450 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
11460 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
11470 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11480 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
11490 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
114a0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
114b0 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
114c0 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
114d0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
114e0 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
114f0 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
11500 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
11510 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
11520 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
11530 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
11540 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
11550 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
11560 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
11570 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
11580 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
11590 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
115a0 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
115b0 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
115c0 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
115d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
115e0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
115f0 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
11600 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
11610 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11620 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
11630 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
11640 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
11650 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
11660 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
11670 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
11680 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
11690 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
116a0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
116b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
116c0 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
116d0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
116e0 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
116f0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11700 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
11710 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11720 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
11730 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
11740 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
11750 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
11760 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
11770 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
11780 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
11790 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
117a0 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
117b0 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
117c0 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
117d0 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
117e0 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
117f0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
11800 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
11810 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
11820 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
11830 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
11840 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
11850 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
11860 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
11870 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
11880 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
11890 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
118a0 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
118b0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
118c0 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
118d0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
118e0 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
118f0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
11900 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
11910 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
11920 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
11930 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
11940 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
11950 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c  alize(void);.SQL
11960 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
11970 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
11980 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
11990 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
119a0 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  it(void);.SQLITE
119b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
119c0 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
119d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
119e0 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
119f0 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
11a00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
11a10 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
11a20 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
11a30 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
11a40 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
11a50 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
11a60 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
11a70 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
11a80 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
11a90 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
11aa0 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
11ab0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
11ac0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
11ad0 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
11ae0 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
11af0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
11b00 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
11b10 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
11b20 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
11b30 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
11b40 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
11b50 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   needs..**.** <b
11b60 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  >The sqlite3_con
11b70 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
11b80 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
11b90 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  e. The applicati
11ba0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72  on.** must ensur
11bb0 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20  e that no other 
11bc0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11bd0 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79  s are invoked by
11be0 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64   other.** thread
11bf0 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  s while sqlite3_
11c00 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e  config() is runn
11c10 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54  ing.</b>.**.** T
11c20 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
11c30 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  g() interface.**
11c40 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
11c50 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
11c60 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
11c70 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
11c80 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11c90 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
11ca0 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
11cb0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
11cc0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
11cd0 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
11ce0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
11cf0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
11d00 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
11d10 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11d20 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
11d30 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
11d40 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
11d50 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
11d60 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
11d70 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
11d80 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
11d90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
11da0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
11db0 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
11dc0 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
11dd0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
11de0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
11df0 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
11e00 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
11e10 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
11e20 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
11e30 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
11e40 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
11e50 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
11e60 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
11e70 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
11e80 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
11e90 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
11ea0 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
11eb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
11ec0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
11ed0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11ee0 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
11ef0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
11f00 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
11f10 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
11f20 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
11f30 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
11f40 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
11f50 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
11f60 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
11f70 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
11f80 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51  ror code]..*/.SQ
11f90 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
11fa0 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
11fb0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
11fc0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
11fd0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11fe0 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
11ff0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
12000 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
12010 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
12020 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
12030 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
12040 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
12050 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12060 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
12070 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
12080 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
12090 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
120a0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
120b0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
120c0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
120d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
120e0 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
120f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
12100 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
12110 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
12120 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
12130 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
12140 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
12150 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
12160 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
12170 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
12180 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
12190 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
121a0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
121b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
121c0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
121d0 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
121e0 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
121f0 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
12200 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
12210 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
12220 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
12230 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
12240 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
12250 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
12260 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
12270 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
12280 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
12290 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
122a0 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
122b0 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
122c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
122d0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
122e0 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
122f0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
12300 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
12310 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
12320 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
12330 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
12340 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
12350 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
12360 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
12370 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
12380 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
12390 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
123a0 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
123b0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
123c0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
123d0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
123e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
123f0 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
12400 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12410 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
12420 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12430 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
12440 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
12450 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
12460 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
12470 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
12480 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
12490 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
124a0 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
124b0 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
124c0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
124d0 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
124e0 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
124f0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
12500 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12510 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
12520 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
12530 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
12540 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
12550 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
12560 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
12570 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
12580 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
12590 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
125a0 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
125b0 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
125c0 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
125d0 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
125e0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
125f0 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
12600 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
12610 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
12620 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
12630 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
12640 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
12650 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
12660 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
12670 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
12680 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
12690 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
126a0 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
126b0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
126c0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
126d0 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
126e0 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
126f0 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
12700 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
12710 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
12720 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
12730 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
12740 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
12750 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
12760 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
12770 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
12780 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
12790 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
127a0 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
127b0 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
127c0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
127d0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
127e0 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
127f0 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
12800 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
12810 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
12820 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
12830 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
12840 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
12850 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
12860 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
12870 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
12880 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
12890 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
128a0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
128b0 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
128c0 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
128d0 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
128e0 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
128f0 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
12900 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
12910 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
12920 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
12930 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
12940 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
12950 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
12960 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
12970 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12980 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
12990 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
129a0 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
129b0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
129c0 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
129d0 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
129e0 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
129f0 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
12a00 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
12a10 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
12a20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
12a30 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
12a40 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
12a50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12a60 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
12a70 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
12a80 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
12a90 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
12aa0 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
12ab0 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
12ac0 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
12ad0 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
12ae0 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
12af0 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
12b00 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
12b10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
12b20 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
12b30 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
12b40 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
12b50 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
12b60 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
12b70 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
12b80 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
12b90 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
12ba0 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
12bb0 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
12bc0 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
12bd0 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
12be0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
12bf0 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
12c00 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
12c10 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
12c20 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
12c30 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
12c40 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
12c50 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
12c60 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
12c70 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
12c80 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
12c90 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
12ca0 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
12cb0 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
12cc0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
12cd0 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
12ce0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
12cf0 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
12d00 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
12d10 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
12d20 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
12d30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
12d40 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
12d50 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
12d60 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
12d70 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
12d80 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
12d90 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
12da0 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
12db0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
12dc0 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
12dd0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
12de0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12df0 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
12e00 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
12e10 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
12e20 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
12e30 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
12e40 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
12e50 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
12e60 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
12e70 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12e80 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
12e90 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
12ea0 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
12eb0 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
12ec0 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
12ed0 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
12ee0 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
12ef0 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
12f00 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
12f10 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
12f20 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
12f30 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
12f40 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
12f50 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
12f60 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
12f70 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
12f80 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
12f90 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
12fa0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
12fb0 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
12fc0 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
12fd0 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
12fe0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
12ff0 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
13000 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
13010 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
13020 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
13030 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
13040 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
13050 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
13060 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
13070 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
13080 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
13090 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
130a0 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
130b0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
130c0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
130d0 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
130e0 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
130f0 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
13100 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
13110 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
13120 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
13130 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
13140 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
13150 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
13160 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
13170 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
13180 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
13190 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
131a0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
131b0 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
131c0 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
131d0 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
131e0 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
131f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13200 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
13210 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
13220 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
13230 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
13240 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
13250 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
13260 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
13270 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
13280 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
13290 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
132a0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
132b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
132c0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
132d0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
132e0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
132f0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
13300 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
13310 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
13320 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
13330 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
13340 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
13350 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
13360 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
13370 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
13380 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
13390 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
133a0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
133b0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
133c0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
133d0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
133e0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
133f0 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
13400 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
13410 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
13420 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
13430 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
13440 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
13450 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
13460 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
13470 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
13480 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
13490 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
134a0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
134b0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
134c0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
134d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
134e0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
134f0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
13500 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
13510 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
13520 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
13530 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
13540 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
13550 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
13560 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
13570 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
13580 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
13590 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
135a0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
135b0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
135c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
135d0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
135e0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
135f0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
13600 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
13610 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13620 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
13630 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
13640 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
13650 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
13660 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
13670 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
13680 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
13690 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
136a0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
136b0 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
136c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
136d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
136e0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
136f0 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
13700 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
13710 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
13720 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
13730 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
13740 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
13750 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13760 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13770 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
13780 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
13790 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
137a0 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
137b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
137c0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
137d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
137e0 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
137f0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
13800 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
13810 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
13820 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
13830 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
13840 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
13850 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
13860 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
13870 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
13880 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
13890 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
138a0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
138b0 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
138c0 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
138d0 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
138e0 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
138f0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
13900 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
13910 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
13920 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13930 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13940 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13950 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13960 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13970 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13980 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
13990 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
139a0 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
139b0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
139c0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
139d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
139e0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
139f0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
13a00 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
13a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
13a20 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
13a30 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
13a40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13a50 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
13a60 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
13a70 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
13a80 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
13a90 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
13aa0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
13ab0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
13ac0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13ad0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13ae0 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
13af0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
13b00 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
13b10 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
13b20 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
13b30 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
13b40 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
13b50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
13b60 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
13b70 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
13b80 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
13b90 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
13ba0 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
13bb0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
13bc0 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
13bd0 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
13be0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
13bf0 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
13c00 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
13c10 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
13c20 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
13c30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13c40 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
13c50 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
13c60 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
13c70 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
13c80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
13c90 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
13ca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
13cb0 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
13cc0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
13cd0 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
13ce0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13cf0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13d00 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13d10 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13d20 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13d30 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13d40 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
13d50 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
13d60 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
13d70 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
13d80 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
13d90 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
13da0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
13db0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
13dc0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
13dd0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
13de0 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
13df0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
13e00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13e10 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
13e20 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13e30 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
13e40 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13e50 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70  CONFIG_MALLOC op
13e60 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13e70 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13e80 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
13e90 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
13ea0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
13eb0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
13ec0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
13ed0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
13ee0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
13ef0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
13f00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13f10 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
13f20 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
13f30 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
13f40 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13f50 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
13f60 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
13f70 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
13f80 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
13f90 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
13fa0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13fb0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13fc0 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
13fd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13fe0 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
13ff0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14000 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14010 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
14020 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
14030 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
14040 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14050 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
14060 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14070 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14080 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
14090 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
140a0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
140b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
140c0 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
140d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
140e0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
140f0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
14100 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
14110 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
14120 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
14130 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
14140 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
14150 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
14160 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
14170 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
14180 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
14190 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
141a0 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
141b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
141c0 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
141d0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
141e0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
141f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14200 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41  _CONFIG_SMALL_MA
14210 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
14220 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
14230 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
14240 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
14250 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c  ONFIG_SMALL_MALL
14260 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
14270 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14280 6f 66 0a 2a 2a 20 74 79 70 65 20 69 6e 74 2c 20  of.** type int, 
14290 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
142a0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
142b0 69 66 20 74 72 75 65 20 70 72 6f 76 69 64 65 73  if true provides
142c0 20 61 20 68 69 6e 74 20 74 6f 0a 2a 2a 20 53 51   a hint to.** SQ
142d0 4c 69 74 65 20 74 68 61 74 20 69 74 20 73 68 6f  Lite that it sho
142e0 75 6c 64 20 61 76 6f 69 64 20 6c 61 72 67 65 20  uld avoid large 
142f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14300 6e 73 20 69 66 20 70 6f 73 73 69 62 6c 65 2e 0a  ns if possible..
14310 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 72  ** SQLite will r
14320 75 6e 20 66 61 73 74 65 72 20 69 66 20 69 74 20  un faster if it 
14330 69 73 20 66 72 65 65 20 74 6f 20 6d 61 6b 65 20  is free to make 
14340 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  large memory all
14350 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74  ocations,.** but
14360 20 73 6f 6d 65 20 61 70 70 6c 69 63 61 74 69 6f   some applicatio
14370 6e 20 6d 69 67 68 74 20 70 72 65 66 65 72 20 74  n might prefer t
14380 6f 20 72 75 6e 20 73 6c 6f 77 65 72 20 69 6e 20  o run slower in 
14390 65 78 63 68 61 6e 67 65 20 66 6f 72 0a 2a 2a 20  exchange for.** 
143a0 67 75 61 72 61 6e 74 65 65 73 20 61 62 6f 75 74  guarantees about
143b0 20 6d 65 6d 6f 72 79 20 66 72 61 67 6d 65 6e 74   memory fragment
143c0 61 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 70  ation that are p
143d0 6f 73 73 69 62 6c 65 20 69 66 20 6c 61 72 67 65  ossible if large
143e0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  .** allocations 
143f0 61 72 65 20 61 76 6f 69 64 65 64 2e 20 20 54 68  are avoided.  Th
14400 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 72 6d 61  is hint is norma
14410 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20 3c 2f 64 64  lly off..** </dd
14420 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14430 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14440 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
14450 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
14460 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14470 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14480 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e  MEMSTATUS option
14490 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
144a0 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
144b0 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  nt,.** interpret
144c0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
144d0 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
144e0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
144f0 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20  ollection of.** 
14500 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14510 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  n statistics. ^(
14520 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
14530 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14540 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
14550 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  d, the following
14560 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
14570 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
14580 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
14590 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
145a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
145b0 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
145c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
145d0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
145e0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
145f0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
14600 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
14610 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36  [sqlite3_status6
14620 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  4()].**   </ul>)
14630 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
14640 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
14650 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
14660 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
14670 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
14680 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
14690 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
146a0 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
146b0 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
146c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
146d0 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
146e0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
146f0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14700 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14710 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
14720 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
14730 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
14740 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14750 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e  G_SCRATCH option
14760 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73   is no longer us
14770 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ed..** </dd>.**.
14780 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14790 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
147a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
147b0 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
147c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
147d0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
147e0 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63  ACHE option spec
147f0 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70  ifies a memory p
14800 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  ool.** that SQLi
14810 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74  te can use for t
14820 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
14830 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
14840 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20  default page.** 
14850 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
14860 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
14870 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14880 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tion is a no-op 
14890 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
148a0 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
148b0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
148c0 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
148d0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
148e0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
148f0 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65  ]..** ^There are
14900 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
14910 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
14920 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70  G_PAGECACHE: A p
14930 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62  ointer to.** 8-b
14940 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  yte aligned memo
14950 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73  ry (pMem), the s
14960 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
14970 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29   cache line (sz)
14980 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d  ,.** and the num
14990 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e  ber of cache lin
149a0 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
149b0 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
149c0 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
149d0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
149e0 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
149f0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
14a00 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35  tween 512 and 65
14a10 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65  536) plus some e
14a20 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65  xtra bytes for e
14a30 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
14a40 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72  er.  ^The number
14a50 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20   of extra bytes 
14a60 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61  needed by the pa
14a70 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e  ge header.** can
14a80 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
14a90 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  sing [SQLITE_CON
14aa0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
14ab0 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72  ]..** ^It is har
14ac0 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
14ad0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
14ae0 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ory,.** for the 
14af0 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  sz parameter to 
14b00 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e  be larger than n
14b10 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 70  ecessary.  The p
14b20 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  Mem.** argument 
14b30 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
14b40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
14b50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14b60 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
14b70 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f  ed block of memo
14b80 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ry of at least s
14b90 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72  z*N bytes, other
14ba0 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65  wise.** subseque
14bb0 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  nt behavior is u
14bc0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68  ndefined..** ^Wh
14bd0 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e  en pMem is not N
14be0 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
14bf0 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20 74   strive to use t
14c00 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
14c10 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79  ed.** to satisfy
14c20 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65 64   page cache need
14c30 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20  s, falling back 
14c40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
14c50 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61  oc()] if.** a pa
14c60 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73  ge cache line is
14c70 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20   larger than sz 
14c80 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20  bytes or if all 
14c90 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66  of the pMem buff
14ca0 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74  er.** is exhaust
14cb0 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20  ed..** ^If pMem 
14cc0 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73  is NULL and N is
14cd0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
14ce0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
14cf0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73  nnection.** does
14d00 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b   an initial bulk
14d10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
14d20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
14d30 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  y.** from [sqlit
14d40 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66  e3_malloc()] suf
14d50 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61  ficient for N ca
14d60 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69  che lines if N i
14d70 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a  s positive or.**
14d80 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65   of -1024*N byte
14d90 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  s if N is negati
14da0 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69  ve, . ^If additi
14db0 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
14dc0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
14dd0 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
14de0 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
14df0 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c  he initial.** al
14e00 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53  location, then S
14e10 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
14e20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14e30 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20   separately for 
14e40 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e  each.** addition
14e50 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c  al cache line. <
14e60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14e70 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
14e80 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14e90 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
14ea0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14eb0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
14ec0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
14ed0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
14ee0 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53  uffer .** that S
14ef0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66  QLite will use f
14f00 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
14f10 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
14f20 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a  ocation needs.**
14f30 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
14f40 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53  ovided for by [S
14f50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
14f60 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65  ECACHE]..** ^The
14f70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14f80 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  EAP option is on
14f90 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
14fa0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14fb0 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65  ed.** with eithe
14fc0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
14fd0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51  _MEMSYS3] or [SQ
14fe0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
14ff0 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73  YS5] and returns
15000 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
15010 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74  R] if invoked ot
15020 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65  herwise..** ^The
15030 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
15040 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
15050 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a  _CONFIG_HEAP:.**
15060 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
15070 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
15080 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
15090 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
150a0 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
150b0 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
150c0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
150d0 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
150e0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
150f0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
15100 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
15110 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
15120 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
15130 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
15140 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
15150 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
15160 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
15170 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
15180 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
15190 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
151a0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
151b0 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
151c0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
151d0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ULL then the alt
151e0 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
151f0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
15200 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
15210 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
15220 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15230 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
15240 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
15250 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
15260 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
15270 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
15280 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
15290 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
152a0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
152b0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
152c0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
152d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
152e0 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
152f0 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
15300 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
15310 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
15320 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
15330 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
15340 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15350 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15360 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15370 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
15380 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
15390 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
153a0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
153b0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
153c0 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70   which is a.** p
153d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
153e0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
153f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
15400 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
15410 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
15420 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e  specifies altern
15430 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
15440 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
15450 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20  o be used.** in 
15460 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20  place the mutex 
15470 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
15480 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
15490 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
154a0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
154b0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
154c0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
154d0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
154e0 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
154f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
15500 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
15510 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
15520 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
15530 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
15540 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
15550 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
15560 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15570 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
15580 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
15590 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
155a0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
155b0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
155c0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
155d0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
155e0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
155f0 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
15600 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
15610 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
15620 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
15630 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15640 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
15650 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15660 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
15670 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
15680 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15690 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  TMUTEX option ta
156a0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
156b0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
156c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
156d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
156e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
156f0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15700 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
15710 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
15720 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
15730 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
15740 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
15750 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
15760 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
15770 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
15780 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
15790 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
157a0 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
157b0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
157c0 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
157d0 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
157e0 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
157f0 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
15800 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
15810 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
15820 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15830 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
15840 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
15850 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
15860 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
15870 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
15880 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
15890 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
158a0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
158b0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
158c0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
158d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
158e0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
158f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
15900 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
15910 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
15920 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
15930 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
15940 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15950 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
15960 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15970 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
15980 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
15990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
159a0 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b  ASIDE option tak
159b0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
159c0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a   that determine.
159d0 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73  ** the default s
159e0 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ize of lookaside
159f0 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20   memory on each 
15a00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15a10 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
15a20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
15a30 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
15a40 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
15a50 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
15a60 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
15a70 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
15a80 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
15a90 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
15aa0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53  nnection.)^  ^(S
15ab0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
15ac0 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74  KASIDE.** sets t
15ad0 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  he <i>default</i
15ae0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
15af0 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
15b00 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15b10 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b  ].** option to [
15b20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15b30 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
15b40 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
15b50 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
15b60 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
15b70 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
15b80 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
15b90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15ba0 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
15bb0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
15bc0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
15bd0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
15be0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
15bf0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15c00 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
15c10 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
15c20 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
15c30 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
15c40 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
15c50 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
15c60 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65  fies.** the inte
15c70 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f  rface to a custo
15c80 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
15c90 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a  lementation.)^.*
15ca0 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  * ^SQLite makes 
15cb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
15cc0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
15cd0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c  thods2] object.<
15ce0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15cf0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15d00 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
15d10 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15d20 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
15d30 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
15d40 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
15d50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15d60 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15d70 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
15d80 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
15d90 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
15da0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
15db0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a  QLite copies of.
15dc0 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70  ** the current p
15dd0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
15de0 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
15df0 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
15e00 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15e10 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
15e20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15e30 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
15e40 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
15e50 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
15e60 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
15e70 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
15e80 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
15e90 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
15ea0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15eb0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
15ec0 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
15ed0 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
15ee0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
15ef0 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
15f00 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
15f10 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
15f20 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
15f30 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
15f40 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
15f50 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
15f60 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
15f70 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
15f80 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
15f90 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
15fa0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
15fb0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
15fc0 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
15fd0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
15fe0 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
15ff0 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
16000 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
16010 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
16020 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
16030 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16040 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
16050 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
16060 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
16070 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
16080 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
16090 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
160a0 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
160b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
160c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
160d0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
160e0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
160f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
16100 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
16110 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
16120 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
16130 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
16140 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
16150 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
16160 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
16170 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
16180 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
16190 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
161a0 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
161b0 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
161c0 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
161d0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
161e0 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
161f0 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
16200 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
16210 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
16220 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
16230 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
16240 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
16250 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
16260 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
16270 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
16280 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
16290 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
162a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
162b0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
162c0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
162d0 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
162e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
162f0 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
16300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16310 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
16320 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
16330 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
16340 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
16350 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49  f type int..** I
16360 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
16370 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
16380 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
16390 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
163a0 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20  ter is zero,.** 
163b0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
163c0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  g is globally di
163d0 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
163e0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
163f0 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65  obally.** enable
16400 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
16410 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
16420 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
16430 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
16440 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
16450 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
16460 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
16470 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
16480 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
16490 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
164a0 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
164b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
164c0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
164d0 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
164e0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
164f0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
16500 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69  is opened. ^If i
16510 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
16520 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
16530 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
16540 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
16550 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
16560 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
16570 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
16580 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16590 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
165a0 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  ^(By default, UR
165b0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
165c0 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
165d0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
165e0 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
165f0 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
16600 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
16610 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
16620 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e  ymbol defined.)^
16630 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16640 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
16650 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
16660 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
16670 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
16680 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  AN.** <dd>^The S
16690 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
166a0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
166b0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
166c0 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a  single integer.*
166d0 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  * argument which
166e0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
166f0 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  as a boolean in 
16700 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
16710 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  or disable.** th
16720 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
16730 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
16740 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
16750 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
16760 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64  mizer..** ^The d
16770 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
16780 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
16790 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
167a0 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
167b0 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
167c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
167d0 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
167e0 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
167f0 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
16800 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
16810 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
16820 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
16830 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
16840 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
16850 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
16860 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
16870 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
16880 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
16890 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68  alfunction.** wh
168a0 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
168b0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
168c0 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
168d0 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
168e0 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
168f0 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
16900 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
16910 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
16920 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
16930 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
16940 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
16950 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
16960 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16970 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
16980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
16990 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
169a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
169b0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
169c0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
169d0 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
169e0 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
169f0 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
16a00 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
16a10 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
16a20 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
16a30 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
16a40 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
16a50 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
16a60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16a70 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
16a80 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
16a90 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
16aa0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
16ab0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
16ac0 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
16ad0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
16ae0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
16af0 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
16b00 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
16b10 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
16b20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
16b30 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
16b40 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
16b50 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
16b60 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
16b70 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
16b80 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
16b90 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
16ba0 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
16bb0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
16bc0 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
16bd0 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
16be0 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
16bf0 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
16c00 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
16c10 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
16c20 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
16c30 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
16c40 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
16c50 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
16c60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
16c70 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
16c80 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
16c90 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
16ca0 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
16cb0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
16cc0 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
16cd0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
16ce0 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
16cf0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
16d00 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
16d10 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
16d20 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
16d30 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
16d40 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
16d50 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
16d60 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
16d70 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
16d80 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
16d90 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
16da0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
16db0 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
16dc0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16dd0 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
16de0 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
16df0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
16e00 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
16e10 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
16e20 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
16e30 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
16e40 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
16e50 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
16e60 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
16e70 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
16e80 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
16e90 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
16ea0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16eb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
16ec0 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
16ed0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
16ee0 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51  _SIZE.** <dd>^SQ
16ef0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
16f00 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20  _SIZE takes two 
16f10 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28  64-bit integer (
16f20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76  sqlite3_int64) v
16f30 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
16f40 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d  e the default mm
16f50 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74  ap size limit (t
16f60 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
16f70 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d  ng for.** [PRAGM
16f80 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e  A mmap_size]) an
16f90 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  d the maximum al
16fa0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20  lowed mmap size 
16fb0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64  limit..** ^The d
16fc0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63  efault setting c
16fd0 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
16fe0 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73   by each databas
16ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  e connection usi
17000 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65  ng.** either the
17010 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
17020 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20  ze] command, or 
17030 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  by using the.** 
17040 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
17050 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
17060 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61  ntrol.  ^(The ma
17070 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
17080 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20  ap size.** will 
17090 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  be silently trun
170a0 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61  cated if necessa
170b0 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f  ry so that it do
170c0 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68  es not exceed th
170d0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  e.** compile-tim
170e0 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73  e maximum mmap s
170f0 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a  ize set by the.*
17100 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d  * [SQLITE_MAX_MM
17110 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65  AP_SIZE] compile
17120 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a  -time option.)^.
17130 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72  ** ^If either ar
17140 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f  gument to this o
17150 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76  ption is negativ
17160 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67  e, then that arg
17170 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e  ument is.** chan
17180 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69  ged to its compi
17190 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e  le-time default.
171a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
171b0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
171c0 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PSIZE]].** <dt>S
171d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
171e0 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c  32_HEAPSIZE.** <
171f0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17200 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
17210 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f  SIZE option is o
17220 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
17230 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
17240 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f  mpiled for Windo
17250 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ws with the [SQL
17260 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
17270 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
17280 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64  macro.** defined
17290 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  . ^SQLITE_CONFIG
172a0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
172b0 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75  takes a 32-bit u
172c0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
172d0 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70  value.** that sp
172e0 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69  ecifies the maxi
172f0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20  mum size of the 
17300 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a  created heap..**
17310 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17320 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
17330 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17340 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17350 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  DRSZ.** <dd>^The
17360 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17370 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69  CACHE_HDRSZ opti
17380 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17390 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
173a0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
173b0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
173c0 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20  and writes into 
173d0 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65  that integer the
173e0 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
173f0 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61  .** bytes per pa
17400 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  ge required for 
17410 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51  each page in [SQ
17420 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
17430 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61  CACHE]..** The a
17440 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73  mount of extra s
17450 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61  pace required ca
17460 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69  n change dependi
17470 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ng on the compil
17480 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c  er,.** target pl
17490 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69  atform, and SQLi
174a0 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  te version..**.*
174b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
174c0 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  G_PMASZ]].** <dt
174d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
174e0 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  MASZ.** <dd>^The
174f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17500 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  MASZ option take
17510 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
17520 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
17530 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   an unsigned int
17540 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68  eger and sets th
17550 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  e "Minimum PMA S
17560 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c  ize" for the mul
17570 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f  tithreaded.** so
17580 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74  rter to that int
17590 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75  eger.  The defau
175a0 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  lt minimum PMA S
175b0 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68  ize is set by th
175c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52  e.** [SQLITE_SOR
175d0 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69  TER_PMASZ] compi
175e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
175f0 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65   New threads are
17600 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20   launched.** to 
17610 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f  help with sort o
17620 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d  perations when m
17630 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72  ultithreaded sor
17640 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c  ting.** is enabl
17650 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50  ed (using the [P
17660 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63  RAGMA threads] c
17670 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20  ommand) and the 
17680 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e  amount of conten
17690 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65  t.** to be sorte
176a0 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61  d exceeds the pa
176b0 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68  ge size times th
176c0 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65  e minimum of the
176d0 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68  .** [PRAGMA cach
176e0 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20  e_size] setting 
176f0 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a  and this value..
17700 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17710 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
17720 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  PILL]].** <dt>SQ
17730 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
17740 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64  JRNL_SPILL.** <d
17750 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
17760 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
17770 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ILL option takes
17780 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
17790 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63  ter which.** bec
177a0 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d  omes the [statem
177b0 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69  ent journal] spi
177c0 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73  ll-to-disk thres
177d0 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74  hold.  .** [Stat
177e0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20  ement journals] 
177f0 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f  are held in memo
17800 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73  ry until their s
17810 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a  ize (in bytes).*
17820 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74  * exceeds this t
17830 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69  hreshold, at whi
17840 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72  ch point they ar
17850 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  e written to dis
17860 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20  k..** Or if the 
17870 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c  threshold is -1,
17880 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
17890 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68  als are always h
178a0 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65  eld.** exclusive
178b0 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ly in memory..**
178c0 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74   Since many stat
178d0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e  ement journals n
178e0 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67  ever become larg
178f0 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73  e, setting the s
17900 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c  pill.** threshol
17910 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63  d to a value suc
17920 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67  h as 64KiB can g
17930 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68  reatly reduce th
17940 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49  e amount of.** I
17950 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73  /O required to s
17960 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74  upport statement
17970 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   rollback..** Th
17980 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
17990 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67  for this setting
179a0 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62   is controlled b
179b0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
179c0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
179d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
179e0 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  tion..** </dl>.*
179f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17a00 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
17a10 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
17a20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17a30 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
17a40 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
17a50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17a60 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
17a70 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
17a80 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
17a90 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
17aa0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
17ab0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
17ac0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
17ad0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17ae0 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
17af0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
17b00 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
17b10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17b20 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
17b30 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
17b40 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
17b50 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
17b60 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
17b70 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
17b80 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
17b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
17ba0 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
17bb0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
17bc0 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
17bd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17be0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
17bf0 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
17c00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17c10 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
17c20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
17c30 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
17c40 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
17c50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17c60 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
17c70 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
17c80 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
17c90 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
17ca0 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
17cb0 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
17cc0 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
17cd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17ce0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
17cf0 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
17d00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17d10 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
17d20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
17d30 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
17d40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
17d50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
17d60 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
17d70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
17d80 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
17d90 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
17da0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17db0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
17dc0 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
17dd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17de0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17df0 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
17e00 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
17e10 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
17e20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17e30 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
17e40 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
17e50 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
17e60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17e70 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
17e80 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
17e90 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
17ea0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
17eb0 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
17ec0 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
17ed0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17ee0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
17ef0 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
17f00 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
17f10 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
17f20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17f30 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17f40 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
17f50 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
17f60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17f70 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20  G_PCACHE_HDRSZ  
17f80 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74        24  /* int
17f90 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65   *psz */.#define
17fa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17fb0 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20  MASZ            
17fc0 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e     25  /* unsign
17fd0 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a  ed int szPma */.
17fe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17ff0 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
18000 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a  PILL      26  /*
18010 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64   int nByte */.#d
18020 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18030 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43  FIG_SMALL_MALLOC
18040 20 20 20 20 20 20 20 20 32 37 20 20 2f 2a 20 62          27  /* b
18050 6f 6f 6c 65 61 6e 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  oolean */../*.**
18060 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
18070 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
18080 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
18090 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
180a0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
180b0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
180c0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
180d0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
180e0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
180f0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
18100 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
18110 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18120 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
18130 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
18140 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
18150 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
18160 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
18170 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
18180 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
18190 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
181a0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
181b0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
181c0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
181d0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
181e0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
181f0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
18200 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
18210 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
18220 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
18230 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
18240 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
18250 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
18260 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
18270 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
18280 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
18290 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
182a0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
182b0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
182c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
182d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
182e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
182f0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
18300 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
18310 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
18320 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
18330 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
18340 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
18350 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
18360 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
18370 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
18380 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
18390 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
183a0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
183b0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
183c0 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
183d0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
183e0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
183f0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
18400 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
18410 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
18420 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
18430 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
18440 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
18450 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
18460 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
18470 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
18480 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
18490 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
184a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
184b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
184c0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
184d0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
184e0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
184f0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
18500 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
18510 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
18520 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
18530 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
18540 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
18550 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
18560 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
18570 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
18580 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
18590 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
185a0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
185b0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
185c0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
185d0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
185e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
185f0 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
18600 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18610 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
18620 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
18630 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
18640 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
18650 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
18660 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
18670 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
18680 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
18690 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
186a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
186b0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
186c0 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
186d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
186e0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
186f0 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
18700 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
18710 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
18720 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
18730 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
18740 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
18750 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
18760 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
18770 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
18780 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
18790 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
187a0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
187b0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
187c0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
187d0 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
187e0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
187f0 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
18800 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
18810 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
18820 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
18830 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
18840 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
18850 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
18860 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
18870 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
18880 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
18890 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
188a0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
188b0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
188c0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
188d0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
188e0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
188f0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
18900 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
18910 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
18920 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
18930 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
18940 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
18950 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
18960 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
18970 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
18980 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
18990 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
189a0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
189b0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
189c0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
189d0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
189e0 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
189f0 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
18a00 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
18a10 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
18a20 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18a30 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
18a40 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
18a50 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
18a60 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
18a70 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18a80 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
18a90 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18aa0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18ab0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
18ac0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
18ad0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
18ae0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
18af0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
18b00 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
18b10 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
18b20 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
18b30 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
18b40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
18b50 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
18b60 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
18b70 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
18b80 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
18b90 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
18ba0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
18bb0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
18bc0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
18bd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18be0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18bf0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18c00 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18c10 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18c20 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
18c30 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
18c40 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
18c50 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
18c60 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
18c70 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
18c80 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
18c90 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
18ca0 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
18cb0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
18cc0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
18cd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18ce0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18cf0 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
18d00 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  NIZER</dt>.** <d
18d10 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18d20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
18d30 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
18d40 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a   two-argument.**
18d50 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
18d60 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28  [fts3_tokenizer(
18d70 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63  )] function whic
18d80 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  h is part of the
18d90 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d  .** [FTS3] full-
18da0 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69  text search engi
18db0 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a  ne extension..**
18dc0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
18dd0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
18de0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
18df0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18e00 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
18e10 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
18e20 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
18e30 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69  zer() or.** posi
18e40 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66  tive to enable f
18e50 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
18e60 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
18e70 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
18e80 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  .** unchanged..*
18e90 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
18ea0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18eb0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
18ec0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
18ed0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
18ee0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
18ef0 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e  ether fts3_token
18f00 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
18f10 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
18f20 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18f30 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18f40 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
18f50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
18f60 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
18f70 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
18f80 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
18f90 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
18fa0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
18fb0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c  BCONFIG_ENABLE_L
18fc0 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64  OAD_EXTENSION</d
18fd0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18fe0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
18ff0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
19000 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  able the [sqlite
19010 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
19020 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
19030 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f   independently o
19040 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  f the [load_exte
19050 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e  nsion()] SQL fun
19060 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73  ction..** The [s
19070 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
19080 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
19090 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  API enables or d
190a0 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65  isables both the
190b0 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74  .** C-API [sqlit
190c0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
190d0 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c  n()] and the SQL
190e0 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f   function [load_
190f0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a  extension()]..**
19100 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
19110 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19120 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68  arguments..** Wh
19130 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  en the first arg
19140 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e  ument to this in
19150 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 68  terface is 1, th
19160 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50  en only the C-AP
19170 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20  I is.** enabled 
19180 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
19190 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73  tion remains dis
191a0 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66  abled.  If the f
191b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
191c0 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61  .** this interfa
191d0 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f  ce is 0, then bo
191e0 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64  th the C-API and
191f0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
19200 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a  n are disabled..
19210 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20  ** If the first 
19220 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20  argument is -1, 
19230 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20  then no changes 
19240 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74  are made to stat
19250 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a  e of either the.
19260 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20  ** C-API or the 
19270 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
19280 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
19290 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
192a0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
192b0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
192c0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
192d0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
192e0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  ther [sqlite3_lo
192f0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
19300 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
19310 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
19320 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  led following th
19330 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
19340 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
19350 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20  ay.** be a NULL 
19360 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63  pointer, in whic
19370 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
19380 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19390 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  ported back..** 
193a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
193b0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
193c0 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a  MAINDBNAME</dt>.
193d0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
193e0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
193f0 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65 20  change the name 
19400 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64 61  of the "main" da
19410 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61  tabase.** schema
19420 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72 67  .  ^The sole arg
19430 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
19440 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74  er to a constant
19450 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20   UTF8 string.** 
19460 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d  which will becom
19470 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d 61  e the new schema
19480 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f   name in place o
19490 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69  f "main".  ^SQLi
194a0 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d  te.** does not m
194b0 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
194c0 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65 6d  e new main schem
194d0 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20 73  a name string, s
194e0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
194f0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
19500 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d 65   that the argume
19510 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  nt passed into t
19520 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70 74  his DBCONFIG opt
19530 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ion is unchanged
19540 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72 20  .** until after 
19550 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19560 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
19570 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
19580 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19590 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c  IG_NO_CKPT_ON_CL
195a0 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  OSE</dt>.** <dd>
195b0 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61   Usually, when a
195c0 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61 6c   database in wal
195d0 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64 20   mode is closed 
195e0 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f 6d  or detached from
195f0 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   a .** database 
19600 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20 63  handle, SQLite c
19610 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77 69  hecks if this wi
19620 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ll mean that the
19630 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a  re are now no .*
19640 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74  * connections at
19650 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74 61   all to the data
19660 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74 20  base. If so, it 
19670 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63 6b  performs a check
19680 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74  point .** operat
19690 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73 69  ion before closi
196a0 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ng the connectio
196b0 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d  n. This option m
196c0 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a  ay be used to.**
196d0 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20 62   override this b
196e0 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66 69  ehaviour. The fi
196f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61  rst parameter pa
19700 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65  ssed to this ope
19710 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20  ration.** is an 
19720 69 6e 74 65 67 65 72 20 2d 20 70 6f 73 69 74 69  integer - positi
19730 76 65 20 74 6f 20 64 69 73 61 62 6c 65 20 63 68  ve to disable ch
19740 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f  eckpoints-on-clo
19750 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68 65  se, or zero (the
19760 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f 20  .** default) to 
19770 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20 61 6e 64  enable them, and
19780 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
19790 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
197a0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
197b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
197c0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
197d0 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  o an integer.** 
197e0 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72  into which is wr
197f0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
19800 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
19810 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
19820 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62 65  close.** have be
19830 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20  en disabled - 0 
19840 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  if they are not 
19850 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20 74  disabled, 1 if t
19860 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64  hey are..** </dd
19870 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
19880 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19890 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20  LE_QPSG</dt>.** 
198a0 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45  <dd>^(The SQLITE
198b0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
198c0 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61 63 74  _QPSG option act
198d0 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69  ivates or deacti
198e0 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b 71 75  vates.** the [qu
198f0 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74 61 62  ery planner stab
19900 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65 65 5d  ility guarantee]
19910 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e 20 74   (QPSG).  When t
19920 68 65 20 51 50 53 47 20 69 73 20 61 63 74 69 76  he QPSG is activ
19930 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 53  e,.** a single S
19940 51 4c 20 71 75 65 72 79 20 73 74 61 74 65 6d 65  QL query stateme
19950 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75  nt will always u
19960 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  se the same algo
19970 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65 73 73  rithm regardless
19980 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20 6f 66  .** of values of
19990 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
199a0 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53 47 20  rs].)^ The QPSG 
199b0 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20 71 75  disables some qu
199c0 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ery optimization
199d0 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b 20 61  s.** that look a
199e0 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20  t the values of 
199f0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
19a00 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61 6b 65  , which can make
19a10 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a 2a 2a   some queries.**
19a20 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20 74 68   slower.  But th
19a30 65 20 51 50 53 47 20 68 61 73 20 74 68 65 20 61  e QPSG has the a
19a40 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f 72 65  dvantage of more
19a50 20 70 72 65 64 69 63 74 61 62 6c 65 20 62 65 68   predictable beh
19a60 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a 2a 20  avior.  With.** 
19a70 74 68 65 20 51 50 53 47 20 61 63 74 69 76 65 2c  the QPSG active,
19a80 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
19a90 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
19aa0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e 20 74   query plan in t
19ab0 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a 20 77  he field as.** w
19ac0 61 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  as used during t
19ad0 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20 6c 61  esting in the la
19ae0 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  b..** The first 
19af0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
19b00 20 73 65 74 74 69 6e 67 20 69 73 20 61 6e 20 69   setting is an i
19b10 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
19b20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 0a 2a 2a  0 to disable .**
19b30 20 74 68 65 20 51 50 53 47 2c 20 70 6f 73 69 74   the QPSG, posit
19b40 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 51 50  ive to enable QP
19b50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20  SG, or negative 
19b60 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
19b70 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ting.** unchange
19b80 64 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  d. The second pa
19b90 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
19ba0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
19bb0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
19bc0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
19bd0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
19be0 68 65 74 68 65 72 20 74 68 65 20 51 50 53 47 20  hether the QPSG 
19bf0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
19c00 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
19c10 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 0a 2a  ing this call..*
19c20 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
19c30 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
19c40 47 5f 54 52 49 47 47 45 52 5f 45 51 50 3c 2f 64  G_TRIGGER_EQP</d
19c50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 20 64 65  t>.** <dd> By de
19c60 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 74 70 75  fault, the outpu
19c70 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 51 55 45  t of EXPLAIN QUE
19c80 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e 64 73  RY PLAN commands
19c90 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20 69 6e   does not .** in
19ca0 63 6c 75 64 65 20 6f 75 74 70 75 74 20 66 6f 72  clude output for
19cb0 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e 73 20   any operations 
19cc0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 72 69  performed by tri
19cd0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 54  gger programs. T
19ce0 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  his.** option is
19cf0 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
19d00 63 6c 65 61 72 20 28 74 68 65 20 64 65 66 61 75  clear (the defau
19d10 6c 74 29 20 61 20 66 6c 61 67 20 74 68 61 74 20  lt) a flag that 
19d20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a 2a 2a 20  governs this.** 
19d30 62 65 68 61 76 69 6f 72 2e 20 54 68 65 20 66 69  behavior. The fi
19d40 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61  rst parameter pa
19d50 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65  ssed to this ope
19d60 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e 74  ration is an int
19d70 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73 69 74 69  eger -.** positi
19d80 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 6f 75 74  ve to enable out
19d90 70 75 74 20 66 6f 72 20 74 72 69 67 67 65 72 20  put for trigger 
19da0 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 7a 65 72  programs, or zer
19db0 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 69 74 2c  o to disable it,
19dc0 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69 76 65 20  .** or negative 
19dd0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
19de0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
19df0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
19e00 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
19e10 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
19e20 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  er into which is
19e30 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 30 20 6f   written .** 0 o
19e40 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
19e50 77 68 65 74 68 65 72 20 6f 75 74 70 75 74 2d 66  whether output-f
19e60 6f 72 2d 74 72 69 67 67 65 72 73 20 68 61 73 20  or-triggers has 
19e70 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20  been disabled - 
19e80 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 73 20 6e  0 if .** it is n
19e90 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
19ea0 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 20 3c 2f  f it is.  .** </
19eb0 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
19ec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19ed0 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41  BCONFIG_MAINDBNA
19ee0 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31 30  ME            10
19ef0 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72  00 /* const char
19f00 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19f10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
19f20 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20  KASIDE          
19f30 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a     1001 /* void*
19f40 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
19f50 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19f60 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
19f70 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f            1002 /
19f80 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
19f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19fa0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
19fb0 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33  GGER        1003
19fc0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
19fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19fe0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
19ff0 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30  TS3_TOKENIZER 10
1a000 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  04 /* int int* *
1a010 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a020 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1a030 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
1a040 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1005 /* int int*
1a050 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a060 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
1a070 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20  KPT_ON_CLOSE    
1a080 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e    1006 /* int in
1a090 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1a0a0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1a0b0 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20 20 20  ABLE_QPSG       
1a0c0 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e 74 20      1007 /* int 
1a0d0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1a0e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a0f0 54 52 49 47 47 45 52 5f 45 51 50 20 20 20 20 20  TRIGGER_EQP     
1a100 20 20 20 20 20 20 31 30 30 38 20 2f 2a 20 69 6e        1008 /* in
1a110 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1a120 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1a130 47 5f 4d 41 58 20 20 20 20 20 20 20 20 20 20 20  G_MAX           
1a140 20 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a 20          1008 /* 
1a150 4c 61 72 67 65 73 74 20 44 42 43 4f 4e 46 49 47  Largest DBCONFIG
1a160 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1a170 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
1a180 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
1a190 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
1a1a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a1b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1a1c0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
1a1d0 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
1a1e0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
1a1f0 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
1a200 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1a210 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
1a220 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
1a230 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
1a240 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
1a250 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
1a260 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
1a270 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
1a280 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1a290 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1a2a0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
1a2b0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
1a2c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a2d0 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
1a2e0 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Rowid.** METHOD:
1a2f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1a300 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
1a310 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
1a320 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
1a330 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
1a340 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
1a350 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
1a360 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
1a370 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
1a380 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
1a390 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
1a3a0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
1a3b0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
1a3c0 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
1a3d0 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
1a3e0 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
1a3f0 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
1a400 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
1a410 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
1a420 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
1a430 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
1a440 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
1a450 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
1a460 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
1a470 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
1a480 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
1a490 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
1a4a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1a4b0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1a4c0 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
1a4d0 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74  face usually ret
1a4e0 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
1a4f0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20   of.** the most 
1a500 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
1a510 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
1a520 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
1a530 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
1a540 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
1a550 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49  connection D. ^I
1a560 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54  nserts into [WIT
1a570 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
1a580 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  es are not.** re
1a590 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73  corded. ^If no s
1a5a0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
1a5b0 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  T]s into rowid t
1a5c0 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 20  ables have ever 
1a5d0 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20  occurred .** on 
1a5e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a5f0 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20  nection D, then 
1a600 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1a610 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74  ert_rowid(D) ret
1a620 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a  urns .** zero..*
1a630 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20  *.** As well as 
1a640 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61  being set automa
1a650 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20  tically as rows 
1a660 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74  are inserted int
1a670 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61  o database.** ta
1a680 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  bles, the value 
1a690 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
1a6a0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
1a6b0 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20   set explicitly 
1a6c0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
1a6d0 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
1a6e0 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f  owid()].**.** So
1a6f0 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  me virtual table
1a700 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
1a710 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73   may INSERT rows
1a720 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
1a730 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  es as.** part of
1a740 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72   committing a tr
1a750 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20  ansaction (e.g. 
1a760 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 63  to flush data ac
1a770 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d  cumulated in mem
1a780 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e  ory.** to disk).
1a790 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 75   In this case su
1a7a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1a7b0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
1a7c0 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64  return the rowid
1a7d0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1a7e0 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e  ith these intern
1a7f0 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74  al INSERT operat
1a800 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64  ions, which lead
1a810 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69  s to .** unintui
1a820 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69  tive results. Vi
1a830 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
1a840 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74  ementations that
1a850 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77   do write to row
1a860 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20  id.** tables in 
1a870 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f  this way can avo
1a880 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20  id this problem 
1a890 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65  by restoring the
1a8a0 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f   original .** ro
1a8b0 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20  wid value using 
1a8c0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73  [sqlite3_set_las
1a8d0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1a8e0 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  ] before returni
1a8f0 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74  ng .** control t
1a900 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a  o the user..**.*
1a910 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
1a920 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
1a930 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e 20   a trigger then 
1a940 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
1a950 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65  l .** return the
1a960 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
1a970 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 20  inserted row as 
1a980 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
1a990 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69  ger is .** runni
1a9a0 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69  ng. Once the tri
1a9b0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64  gger program end
1a9c0 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
1a9d0 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
1a9e0 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
1a9f0 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
1aa00 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
1aa10 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e  ger was fired.)^
1aa20 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
1aa30 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
1aa40 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
1aa50 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
1aa60 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
1aa70 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
1aa80 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
1aa90 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1aaa0 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
1aab0 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
1aac0 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
1aad0 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
1aae0 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
1aaf0 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
1ab00 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
1ab10 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
1ab20 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1ab30 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
1ab40 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
1ab50 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
1ab60 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
1ab70 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
1ab80 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
1ab90 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
1aba0 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
1abb0 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
1abc0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
1abd0 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
1abe0 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
1abf0 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
1ac00 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
1ac10 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
1ac20 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
1ac30 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
1ac40 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
1ac50 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
1ac60 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
1ac70 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
1ac80 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
1ac90 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
1aca0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
1acb0 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
1acc0 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
1acd0 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
1ace0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
1acf0 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
1ad00 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
1ad10 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
1ad20 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
1ad30 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
1ad40 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1ad50 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1ad60 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
1ad70 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
1ad80 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
1ad90 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
1ada0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
1adb0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1adc0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
1add0 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
1ade0 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
1adf0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
1ae00 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
1ae10 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1ae20 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
1ae30 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
1ae40 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
1ae50 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
1ae60 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
1ae70 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
1ae80 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
1ae90 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c   [rowid]..*/.SQL
1aea0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1aeb0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
1aec0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1aed0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1aee0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1aef0 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20  the Last Insert 
1af00 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20  Rowid value..** 
1af10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1af20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1af30 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1af40 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65  t_rowid(D, R) me
1af50 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20  thod allows the 
1af60 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a  application to.*
1af70 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20  * set the value 
1af80 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c  returned by call
1af90 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  ing sqlite3_last
1afa0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
1afb0 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75   to R .** withou
1afc0 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f  t inserting a ro
1afd0 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  w into the datab
1afe0 61 73 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ase..*/.SQLITE_A
1aff0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1b000 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1b010 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 2c 73  rowid(sqlite3*,s
1b020 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
1b030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b040 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
1b050 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1b060 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1b070 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1b080 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1b090 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1b0a0 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69  rows modified, i
1b0b0 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65  nserted or.** de
1b0c0 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
1b0d0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
1b0e0 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
1b0f0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  ATE or DELETE.**
1b100 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
1b110 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b120 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
1b130 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  by the only para
1b140 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75  meter..** ^Execu
1b150 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
1b160 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
1b170 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f  ment does not mo
1b180 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a  dify the value.*
1b190 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  * returned by th
1b1a0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
1b1b0 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ** ^Only changes
1b1c0 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62   made directly b
1b1d0 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
1b1e0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1b1f0 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20  tatement are.** 
1b200 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78  considered - aux
1b210 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
1b220 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45  aused by [CREATE
1b230 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
1b240 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69  ers], .** [forei
1b250 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1b260 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  or [REPLACE] con
1b270 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1b280 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  on are not count
1b290 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67  ed..** .** Chang
1b2a0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
1b2b0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
1b2c0 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41  d by .** [INSTEA
1b2d0 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49  D OF trigger | I
1b2e0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1b2f0 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  rs] are not coun
1b300 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20  ted. ^The value 
1b310 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
1b320 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1b330 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  ) immediately af
1b340 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55  ter an INSERT, U
1b350 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c  PDATE or .** DEL
1b360 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75  ETE statement ru
1b370 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61  n on a view is a
1b380 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79  lways zero. Only
1b390 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f   changes made to
1b3a0 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73   real .** tables
1b3b0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
1b3c0 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d  .** Things are m
1b3d0 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20  ore complicated 
1b3e0 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  if the sqlite3_c
1b3f0 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1b400 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64  n is.** executed
1b410 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72   while a trigger
1b420 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e   program is runn
1b430 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61  ing. This may ha
1b440 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70  ppen if the.** p
1b450 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20  rogram uses the 
1b460 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1b470 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20  unction], or if 
1b480 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62  some other callb
1b490 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1b4a0 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f  invokes sqlite3_
1b4b0 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74  changes() direct
1b4c0 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a  ly. Essentially:
1b4d0 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  .** .** <ul>.** 
1b4e0 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20    <li> ^(Before 
1b4f0 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67  entering a trigg
1b500 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76  er program the v
1b510 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1b520 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74  .**        sqlit
1b530 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
1b540 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20  ction is saved. 
1b550 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65  After the trigge
1b560 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20  r program .**   
1b570 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65       has finishe
1b580 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  d, the original 
1b590 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65  value is restore
1b5a0 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c  d.)^.** .**   <l
1b5b0 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72  i> ^(Within a tr
1b5c0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61  igger program ea
1b5d0 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ch INSERT, UPDAT
1b5e0 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a  E and DELETE .**
1b5f0 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
1b600 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65  t sets the value
1b610 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1b620 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1b630 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63  **        upon c
1b640 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72  ompletion as nor
1b650 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20  mal. Of course, 
1b660 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20  this value will 
1b670 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20  not include .** 
1b680 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67         any chang
1b690 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  es performed by 
1b6a0 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73  sub-triggers, as
1b6b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
1b6c0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1b6d0 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20    value will be 
1b6e0 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72  saved and restor
1b6f0 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75  ed after each su
1b700 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75  b-trigger has ru
1b710 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  n.)^.** </ul>.**
1b720 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73   .** ^This means
1b730 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61   that if the cha
1b740 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1b750 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29  ion (or similar)
1b760 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74   is used.** by t
1b770 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c  he first INSERT,
1b780 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1b790 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1b7a0 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74  in a trigger, it
1b7b0 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65   .** returns the
1b7c0 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68   value as set wh
1b7d0 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73  en the calling s
1b7e0 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65  tatement began e
1b7f0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66  xecuting..** ^If
1b800 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74   it is used by t
1b810 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62  he second or sub
1b820 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61  sequent such sta
1b830 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1b840 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67  trigger .** prog
1b850 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72  ram, the value r
1b860 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73  eturned reflects
1b870 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1b880 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20  ows modified by 
1b890 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73  the .** previous
1b8a0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1b8b0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1b8c0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
1b8d0 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a  ame trigger..**.
1b8e0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
1b8f0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1b900 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1b910 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1b920 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1b930 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
1b940 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1b950 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1b960 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1b970 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
1b980 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
1b990 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1b9a0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
1b9b0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1b9c0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1b9d0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1b9e0 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
1b9f0 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1ba00 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ngful..*/.SQLITE
1ba10 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1ba20 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1ba30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1ba40 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
1ba50 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
1ba60 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
1ba70 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1ba80 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1ba90 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
1baa0 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65  ber of rows inse
1bab0 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f  rted, modified o
1bac0 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
1bad0 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  all [INSERT], [U
1bae0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
1baf0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f  E] statements co
1bb00 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65  mpleted.** since
1bb10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1bb20 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65  nnection was ope
1bb30 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74  ned, including t
1bb40 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73  hose executed as
1bb50 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67  .** part of trig
1bb60 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45  ger programs. ^E
1bb70 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
1bb80 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
1bb90 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73  tatement.** does
1bba0 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20   not affect the 
1bbb0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1bbc0 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
1bbd0 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a  changes()..** .*
1bbe0 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20  * ^Changes made 
1bbf0 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65  as part of [fore
1bc00 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
1bc10 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
1bc20 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62   the.** count, b
1bc30 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73  ut those made as
1bc40 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45   part of REPLACE
1bc50 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
1bc60 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f  lution are.** no
1bc70 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  t. ^Changes to a
1bc80 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
1bc90 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e  ntercepted by IN
1bca0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1bcb0 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  s .** are not co
1bcc0 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65  unted..** .** Se
1bcd0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
1bce0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1bcf0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
1bd00 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
1bd10 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
1bd20 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
1bd30 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1bd40 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1bd50 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1bd60 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1bd70 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1bd80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1bd90 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
1bda0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
1bdb0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
1bdc0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1bdd0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
1bde0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
1bdf0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  ingful..*/.SQLIT
1be00 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1be10 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1be20 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1be30 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
1be40 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
1be50 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45  ning Query.** ME
1be60 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1be70 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1be80 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
1be90 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
1bea0 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
1beb0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
1bec0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
1bed0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
1bee0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
1bef0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
1bf00 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
1bf10 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
1bf20 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
1bf30 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
1bf40 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
1bf50 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
1bf60 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
1bf70 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
1bf80 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
1bf90 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
1bfa0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1bfb0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
1bfc0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
1bfd0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
1bfe0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
1bff0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
1c000 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
1c010 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
1c020 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1c030 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
1c040 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c050 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
1c060 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
1c070 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
1c080 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1c090 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
1c0a0 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
1c0b0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
1c0c0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
1c0d0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
1c0e0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
1c0f0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
1c100 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
1c110 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
1c120 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
1c130 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
1c140 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
1c150 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
1c160 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
1c170 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
1c180 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
1c190 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
1c1a0 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
1c1b0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
1c1c0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1c1d0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
1c1e0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
1c1f0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
1c200 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
1c210 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
1c220 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
1c230 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
1c240 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
1c250 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
1c260 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
1c270 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
1c280 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
1c290 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
1c2a0 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
1c2b0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
1c2c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c2d0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
1c2e0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
1c2f0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1c300 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1c310 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1c320 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1c330 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
1c340 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
1c350 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
1c360 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
1c370 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
1c380 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
1c390 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
1c3a0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c3b0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
1c3c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1c3d0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1c3e0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
1c3f0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
1c400 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
1c410 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
1c420 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
1c430 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1c440 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
1c450 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c460 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
1c470 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
1c480 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
1c490 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
1c4a0 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
1c4b0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
1c4c0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1c4d0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1c4e0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1c4f0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1c500 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 53  ll returns..*/.S
1c510 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1c520 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1c530 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1c540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
1c550 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
1c560 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
1c570 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
1c580 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1c590 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
1c5a0 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
1c5b0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
1c5c0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
1c5d0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
1c5e0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
1c5f0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1c600 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
1c610 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
1c620 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
1c630 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
1c640 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
1c650 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
1c660 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1c670 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
1c680 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
1c690 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
1c6a0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1c6b0 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
1c6c0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
1c6d0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
1c6e0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
1c6f0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
1c700 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
1c710 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
1c720 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
1c730 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
1c740 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
1c750 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
1c760 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
1c770 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
1c780 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
1c790 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
1c7a0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
1c7b0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
1c7c0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
1c7d0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
1c7e0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
1c7f0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
1c800 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
1c810 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
1c820 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
1c830 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
1c840 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
1c850 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
1c860 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
1c870 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
1c880 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1c890 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
1c8a0 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
1c8b0 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
1c8c0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
1c8d0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
1c8e0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
1c8f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1c900 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1c910 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
1c920 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1c930 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
1c940 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
1c950 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
1c960 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
1c970 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
1c980 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
1c990 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
1c9a0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
1c9b0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
1c9c0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
1c9d0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
1c9e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1c9f0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1ca00 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
1ca10 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1ca20 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
1ca30 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
1ca40 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
1ca50 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1ca60 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
1ca70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
1ca80 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
1ca90 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1caa0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
1cab0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
1cac0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
1cad0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1cae0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
1caf0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1cb00 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1cb10 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
1cb20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1cb30 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1cb40 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1cb50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1cb60 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
1cb70 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
1cb80 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  der..*/.SQLITE_A
1cb90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
1cba0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
1cbb0 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45  ar *sql);.SQLITE
1cbc0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1cbd0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
1cbe0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
1cbf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1cc00 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
1cc10 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
1cc20 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
1cc30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75  ** KEYWORDS: {bu
1cc40 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
1cc50 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c  ack} {busy handl
1cc60 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
1cc70 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1cc80 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1cc90 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f  andler(D,X,P) ro
1cca0 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
1ccb0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1ccc0 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62  .** that might b
1ccd0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
1cce0 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
1ccf0 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
1cd00 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1cd10 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61  ss a database ta
1cd20 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  ble associated w
1cd30 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ith.** [database
1cd40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
1cd50 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hen another thre
1cd60 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
1cd70 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c   has the table l
1cd80 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71  ocked..** The sq
1cd90 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1cda0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  er() interface i
1cdb0 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
1cdc0 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ent.** [sqlite3_
1cdd0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
1cde0 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79  and [PRAGMA busy
1cdf0 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a  _timeout]..**.**
1ce00 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1ce10 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
1ce20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
1ce30 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  Y].** is returne
1ce40 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
1ce50 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
1ce60 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
1ce70 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1ce80 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
1ce90 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
1cea0 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
1ceb0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
1cec0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
1ced0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1cee0 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
1cef0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
1cf00 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
1cf10 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
1cf20 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
1cf30 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
1cf40 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
1cf50 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
1cf60 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
1cf70 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
1cf80 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
1cf90 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
1cfa0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1cfb0 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
1cfc0 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79  voked previously
1cfd0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
1cfe0 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
1cff0 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
1d000 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
1d010 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
1d020 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
1d030 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
1d040 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1d050 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
1d060 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a  Y] is returned.*
1d070 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1d080 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
1d090 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d0a0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
1d0b0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
1d0c0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61  .** is made to a
1d0d0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1d0e0 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  se and the cycle
1d0f0 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
1d100 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
1d110 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
1d120 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
1d130 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
1d140 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
1d150 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
1d160 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
1d170 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
1d180 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
1d190 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
1d1a0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
1d1b0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
1d1c0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
1d1d0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
1d1e0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20  ITE_BUSY].** to 
1d1f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1d200 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
1d210 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79  ing the .** busy
1d220 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
1d230 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
1d240 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
1d250 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1d260 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
1d270 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
1d280 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
1d290 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
1d2a0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
1d2b0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1d2c0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1d2d0 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
1d2e0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
1d2f0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
1d300 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
1d310 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
1d320 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
1d330 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1d340 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
1d350 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
1d360 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
1d370 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
1d380 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1d390 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
1d3a0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
1d3b0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
1d3c0 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
1d3d0 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
1d3e0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
1d3f0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
1d400 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
1d410 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
1d420 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
1d430 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
1d440 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
1d450 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1d460 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
1d470 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
1d480 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
1d490 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
1d4a0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
1d4b0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
1d4c0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
1d4d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1d4e0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1d4f0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1d500 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
1d510 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1d520 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
1d530 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
1d540 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
1d550 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
1d560 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
1d570 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
1d580 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1d590 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f  _timeout()].** o
1d5a0 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52  r evaluating [PR
1d5b0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1d5c0 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65  t=N] will change
1d5d0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
1d5e0 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c  dler and thus cl
1d5f0 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ear any previous
1d600 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64  ly set busy hand
1d610 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
1d620 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
1d630 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
1d640 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
1d650 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
1d660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d670 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1d680 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
1d690 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
1d6a0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1d6b0 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e  dler is not reen
1d6c0 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68  trant.  Any such
1d6d0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
1d6e0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
1d6f0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
1d700 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
1d710 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
1d720 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1d730 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
1d740 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d750 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
1d760 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1d770 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1d780 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1d790 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1d7a0 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  ,int(*)(void*,in
1d7b0 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  t),void*);../*.*
1d7c0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1d7d0 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
1d7e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1d7f0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  3.**.** ^This ro
1d800 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
1d810 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1d820 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
1d830 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
1d840 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
1d850 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
1d860 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
1d870 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
1d880 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
1d890 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
1d8a0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
1d8b0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1d8c0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1d8d0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
1d8e0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
1d8f0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1d900 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1d910 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
1d920 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
1d930 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
1d940 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
1d950 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
1d960 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  E_BUSY]..**.** ^
1d970 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1d980 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1d990 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1d9a0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1d9b0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1d9c0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1d9d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1d9e0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1d9f0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1da00 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1da10 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1da20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e  onnection] at an
1da30 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1da40 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1da50 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1da60 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1da70 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1da80 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1da90 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1daa0 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1dab0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1dac0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1dad0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1dae0 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  :  [PRAGMA busy_
1daf0 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49  timeout].*/.SQLI
1db00 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1db10 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1db20 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1db30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1db40 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1db50 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1db60 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1db70 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1db80 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1db90 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1dba0 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1dbb0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1dbc0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1dbd0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1dbe0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1dbf0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1dc00 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1dc10 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1dc20 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1dc30 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1dc40 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1dc50 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1dc60 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1dc70 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1dc80 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1dc90 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1dca0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1dcb0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1dcc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1dcd0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1dce0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1dcf0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1dd00 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1dd10 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1dd20 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1dd30 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1dd40 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1dd50 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1dd60 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1dd70 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1dd80 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1dd90 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1dda0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1ddb0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1ddc0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1ddd0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1dde0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1ddf0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1de00 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1de10 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1de20 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1de30 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1de40 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1de50 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1de60 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1de70 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1de80 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1de90 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1dea0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1deb0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1dec0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1ded0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1dee0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1def0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1df00 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1df10 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1df20 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1df30 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1df40 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1df50 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1df60 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1df70 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1df80 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1df90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1dfa0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1dfb0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1dfc0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1dfd0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1dfe0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1dff0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1e000 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1e010 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1e020 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1e030 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1e040 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1e050 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1e060 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1e070 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1e080 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1e090 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1e0a0 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1e0b0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1e0c0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1e0d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1e0e0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1e0f0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1e100 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1e110 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1e120 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1e130 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e140 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1e150 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1e160 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1e170 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1e180 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1e190 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1e1a0 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1e1b0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1e1c0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1e1d0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1e1e0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1e1f0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1e200 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1e210 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e220 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1e230 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1e240 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1e250 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1e260 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1e270 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1e280 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1e290 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1e2a0 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1e2b0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1e2c0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1e2d0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1e2e0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1e2f0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1e300 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1e310 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1e320 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1e330 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1e340 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1e350 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1e360 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1e370 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1e380 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1e390 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1e3a0 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1e3b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1e3c0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1e3d0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1e3e0 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1e3f0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1e400 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1e410 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1e420 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1e430 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1e440 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1e450 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1e460 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1e470 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1e480 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1e490 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1e4a0 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1e4b0 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1e4c0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1e4d0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1e4e0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1e4f0 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1e500 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1e510 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1e520 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1e530 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1e540 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1e550 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1e560 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1e570 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1e580 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1e590 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1e5a0 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1e5b0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1e5c0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1e5d0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1e5e0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1e5f0 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1e600 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1e610 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1e620 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1e630 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1e640 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1e650 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1e660 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1e670 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1e680 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1e690 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1e6a0 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1e6b0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1e6c0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1e6d0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1e6e0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1e6f0 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1e700 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1e710 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1e720 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1e730 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1e740 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1e750 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1e760 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1e770 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1e780 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1e790 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1e7a0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1e7b0 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  g()]..*/.SQLITE_
1e7c0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1e7d0 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1e7e0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1e7f0 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1e800 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1e810 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1e820 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1e830 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1e840 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1e850 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1e860 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1e870 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1e880 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1e890 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1e8a0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1e8b0 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1e8c0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1e8d0 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1e8e0 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1e8f0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1e900 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1e910 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1e920 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49   here */.);.SQLI
1e930 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1e940 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1e950 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1e960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e970 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1e980 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1e990 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1e9a0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1e9b0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1e9c0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1e9d0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1e9e0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1e9f0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1ea00 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1ea10 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74   understand most
1ea20 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66   of the common f
1ea30 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1ea40 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  s from.** the st
1ea50 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 70  andard library p
1ea60 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73  rintf() .** plus
1ea70 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1ea80 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f   non-standard fo
1ea90 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51  rmats ([%q], [%Q
1eaa0 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a  ], [%w], and [%z
1eab0 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b  ])..** See the [
1eac0 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28  built-in printf(
1ead0 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
1eae0 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a   for details..**
1eaf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1eb00 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1eb10 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1eb20 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1eb30 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1eb40 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1eb50 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1eb60 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d  ite3_malloc64()]
1eb70 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
1eb80 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1eb90 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
1eba0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
1ebb0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
1ebc0 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
1ebd0 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
1ebe0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1ebf0 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
1ec00 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20 75  malloc64()] is u
1ec10 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1ec20 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
1ec30 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
1ec40 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
1ec50 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1ec60 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
1ec70 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
1ec80 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
1ec90 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
1eca0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1ecb0 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
1ecc0 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
1ecd0 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
1ece0 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
1ecf0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
1ed00 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
1ed10 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
1ed20 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
1ed30 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
1ed40 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1ed50 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
1ed60 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
1ed70 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
1ed80 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
1ed90 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
1eda0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
1edb0 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
1edc0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
1edd0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1ede0 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
1edf0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
1ee00 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
1ee10 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1ee20 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
1ee30 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
1ee40 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
1ee50 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
1ee60 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
1ee70 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
1ee80 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
1ee90 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1eea0 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
1eeb0 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
1eec0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
1eed0 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
1eee0 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
1eef0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
1ef00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1ef10 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
1ef20 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
1ef30 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
1ef40 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
1ef50 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
1ef60 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
1ef70 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1ef80 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
1ef90 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
1efa0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
1efb0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
1efc0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1efd0 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
1efe0 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
1eff0 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
1f000 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
1f010 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
1f020 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
1f030 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
1f040 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
1f050 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
1f060 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
1f070 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
1f080 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1f090 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
1f0a0 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
1f0b0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1f0c0 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  intf()..**.** Se
1f0d0 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d  e also:  [built-
1f0e0 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70  in printf()], [p
1f0f0 72 69 6e 74 66 28 29 20 53 51 4c 20 66 75 6e 63  rintf() SQL func
1f100 74 69 6f 6e 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion].*/.SQLITE_
1f110 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
1f120 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1f130 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49  char*,...);.SQLI
1f140 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1f150 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
1f160 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1f170 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  st);.SQLITE_API 
1f180 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
1f190 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1f1a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1f1b0 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .);.SQLITE_API c
1f1c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
1f1d0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1f1e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1f1f0 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1f200 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1f210 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1f220 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1f230 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1f240 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1f250 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1f260 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1f270 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1f280 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1f290 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1f2a0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1f2b0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1f2c0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1f2d0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1f2e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1f2f0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1f300 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1f310 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1f320 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1f330 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1f340 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1f350 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1f360 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1f370 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1f380 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1f390 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1f3a0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1f3b0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1f3c0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1f3d0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1f3e0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1f3f0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1f400 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1f410 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1f420 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1f430 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1f440 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1f450 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1f460 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1f470 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1f480 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1f490 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f4a0 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f  3_malloc64(N) ro
1f4b0 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74  utine works just
1f4c0 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33   like.** sqlite3
1f4d0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70  _malloc(N) excep
1f4e0 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75  t that N is an u
1f4f0 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69  nsigned 64-bit i
1f500 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1f510 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32  * of a signed 32
1f520 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  -bit integer..**
1f530 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1f540 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1f550 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1f560 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1f570 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1f580 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1f590 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1f5a0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1f5b0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1f5c0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1f5d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1f5e0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1f5f0 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1f600 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1f610 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1f620 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1f630 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1f640 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1f650 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1f660 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1f670 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1f680 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1f690 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1f6a0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1f6b0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1f6c0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1f6d0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1f6e0 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1f6f0 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1f700 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1f710 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1f720 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1f730 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1f740 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1f750 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1f760 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1f770 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1f780 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1f790 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1f7a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f7b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1f7c0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  lloc()..**.** ^T
1f7d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1f7e0 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  oc(X,N) interfac
1f7f0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1f800 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1f810 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f820 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61  n X to be at lea
1f830 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  st N bytes..** ^
1f840 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  If the X paramet
1f850 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1f860 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73  alloc(X,N).** is
1f870 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1f880 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1f890 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1f8a0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1f8b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a  ite3_malloc(N)..
1f8c0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72  ** ^If the N par
1f8d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1f8e0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1f8f0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1f900 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1f910 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1f920 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1f930 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1f940 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73  3_free(X)..** ^s
1f950 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f960 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ,N) returns a po
1f970 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1f980 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1f990 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1f9a0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1f9b0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
1f9c0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76  ent memory is av
1f9d0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1f9e0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1f9f0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1fa00 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1fa10 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1fa20 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1fa30 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1fa40 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1fa50 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1fa60 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1fa70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1fa80 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1fa90 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1faa0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1fab0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1fac0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
1fad0 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c  d N is positive,
1fae0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69   then the.** pri
1faf0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1fb00 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1fb10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1fb20 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e  ealloc64(X,N) in
1fb30 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74  terfaces works t
1fb40 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
1fb50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1fb60 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1fb70 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73   is a 64-bit uns
1fb80 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e  igned integer in
1fb90 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32  stead.** of a 32
1fba0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1fbb0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58  ger..**.** ^If X
1fbc0 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   is a memory all
1fbd0 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73  ocation previous
1fbe0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
1fbf0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1fc00 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
1fc10 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65  lloc64(), sqlite
1fc20 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20  3_realloc(), or 
1fc30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1fc40 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  4(), then.** sql
1fc50 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1fc60 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
1fc70 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c  f that memory al
1fc80 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65  location in byte
1fc90 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  s..** ^The value
1fca0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1fcb0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69  ite3_msize(X) mi
1fcc0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
1fcd0 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  an the number.**
1fce0 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73   of bytes reques
1fcf0 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61  ted when X was a
1fd00 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58  llocated.  ^If X
1fd10 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1fd20 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  er then.** sqlit
1fd30 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1fd40 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20  rns zero.  If X 
1fd50 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68  points to someth
1fd60 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a  ing that is not.
1fd70 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ** the beginning
1fd80 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
1fd90 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20  ation, or if it 
1fda0 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d  points to a form
1fdb0 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65  erly.** valid me
1fdc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1fdd0 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65  that has now bee
1fde0 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68  n freed, then th
1fdf0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
1fe00 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1fe10 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  ) is undefined a
1fe20 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d  nd possibly harm
1fe30 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ful..**.** ^The 
1fe40 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1fe50 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1fe60 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  c(), sqlite3_rea
1fe70 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1fe80 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61  e3_malloc64(), a
1fe90 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1fea0 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77  oc64().** is alw
1feb0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1fec0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1fed0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1fee0 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1fef0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1ff00 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1ff10 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1ff20 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1ff30 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1ff40 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1ff50 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1ff60 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1ff70 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1ff80 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1ff90 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1ffa0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1ffb0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1ffc0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1ffd0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1ffe0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1fff0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
20000 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
20010 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
20020 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
20030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
20040 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
20050 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
20060 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
20070 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
20080 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
20090 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
200a0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
200b0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
200c0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
200d0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
200e0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
200f0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
20100 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
20110 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
20120 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
20130 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
20140 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
20150 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
20160 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
20170 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
20180 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
20190 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
201a0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
201b0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
201c0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
201d0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
201e0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
201f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
20200 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
20210 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
20220 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
20230 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
20240 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
20250 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
20260 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
20270 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
20280 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
20290 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
202a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
202b0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
202c0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
202d0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
202e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
202f0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
20300 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
20310 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
20320 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
20330 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
20340 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
20350 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
20360 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
20370 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
20380 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
20390 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45  loc(int);.SQLITE
203a0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
203b0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
203c0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c  te3_uint64);.SQL
203d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
203e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
203f0 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  id*, int);.SQLIT
20400 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
20410 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f  te3_realloc64(vo
20420 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
20430 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
20440 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72   void sqlite3_fr
20450 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ee(void*);.SQLIT
20460 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69  E_API sqlite3_ui
20470 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69  nt64 sqlite3_msi
20480 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ze(void*);../*.*
20490 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
204a0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
204b0 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
204c0 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
204d0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
204e0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
204f0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
20500 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
20510 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
20520 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
20530 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
20540 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
20550 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
20560 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
20570 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
20580 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
20590 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
205a0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
205b0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
205c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
205d0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
205e0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
205f0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
20600 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
20610 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
20620 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
20630 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
20640 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
20650 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
20660 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
20670 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
20680 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
20690 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
206a0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
206b0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
206c0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
206d0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
206e0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
206f0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
20700 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
20710 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
20720 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
20730 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
20740 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
20750 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
20760 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
20770 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
20780 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
20790 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
207a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
207b0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
207c0 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
207d0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
207e0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
207f0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
20800 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
20810 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
20820 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
20830 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
20840 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20850 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
20860 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
20870 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
20880 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20890 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
208a0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
208b0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
208c0 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
208d0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
208e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
208f0 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  sed(void);.SQLIT
20900 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
20910 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
20920 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
20930 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
20940 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
20950 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
20960 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
20970 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
20980 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
20990 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
209a0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
209b0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
209c0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
209d0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
209e0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
209f0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
20a00 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
20a10 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
20a20 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
20a30 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
20a40 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
20a50 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
20a60 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
20a70 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
20a80 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
20a90 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
20aa0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
20ab0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
20ac0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
20ad0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
20ae0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
20af0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
20b00 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
20b10 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
20b20 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
20b30 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
20b40 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
20b50 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
20b60 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
20b70 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
20b80 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
20b90 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
20ba0 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
20bb0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
20bc0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
20bd0 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
20be0 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
20bf0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
20c00 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
20c10 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
20c20 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
20c30 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
20c40 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
20c50 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
20c60 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
20c70 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
20c80 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
20c90 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
20ca0 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
20cb0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
20cc0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
20cd0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
20ce0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
20cf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
20d00 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
20d10 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c  * method..*/.SQL
20d20 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
20d30 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
20d40 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
20d50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20d60 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
20d70 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
20d80 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
20d90 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59  : sqlite3.** KEY
20da0 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a  WORDS: {authoriz
20db0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a  er callback}.**.
20dc0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
20dd0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
20de0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20df0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
20e00 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
20e10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
20e20 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
20e30 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
20e40 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
20e50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20e60 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
20e70 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
20e80 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
20e90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20ea0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
20eb0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
20ec0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
20ed0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20ee0 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v3()], [sqlite3_
20ef0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73  prepare16()], [s
20f00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20f10 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  _v2()],.** and [
20f20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20f30 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v3()].  ^At va
20f40 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
20f50 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
20f60 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
20f70 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
20f80 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
20f90 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
20fa0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
20fb0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20fc0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
20fd0 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
20fe0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
20ff0 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
21000 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
21010 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
21020 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
21030 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
21040 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
21050 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
21060 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
21070 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
21080 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
21090 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
210a0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
210b0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
210c0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
210d0 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
210e0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
210f0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
21100 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
21110 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
21120 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
21130 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
21140 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
21150 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
21160 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
21170 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
21180 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21190 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
211a0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
211b0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
211c0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
211d0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
211e0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
211f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
21200 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
21210 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
21220 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
21230 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
21240 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
21250 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
21260 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
21270 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
21280 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
21290 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
212a0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
212b0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
212c0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
212d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
212e0 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
212f0 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
21300 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
21310 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
21320 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21330 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
21340 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
21350 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
21360 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
21370 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
21380 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
21390 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
213a0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
213b0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
213c0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
213d0 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
213e0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
213f0 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
21400 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
21410 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
21420 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
21430 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
21440 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
21450 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e  either NULL poin
21460 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72  ters or zero-ter
21470 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a  minated strings.
21480 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  ** that contain 
21490 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
214a0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
214b0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
214c0 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  ized..** Applica
214d0 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79  tions must alway
214e0 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f  s be prepared to
214f0 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c   encounter a NUL
21500 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79  L pointer in any
21510 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64  .** of the third
21520 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78   through the six
21530 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  th parameters of
21540 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
21550 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
21560 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
21570 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
21580 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
21590 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
215a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
215b0 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
215c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
215d0 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
215e0 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
215f0 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
21600 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
21610 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
21620 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
21630 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
21640 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
21650 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
21660 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
21670 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
21680 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
21690 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
216a0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
216b0 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
216c0 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
216d0 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65  a table..** ^Whe
216e0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66  n a table is ref
216f0 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45  erenced by a [SE
21700 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c  LECT] but no col
21710 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a  umn values are.*
21720 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  * extracted from
21730 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72   that table (for
21740 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75   example in a qu
21750 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c  ery like.** "SEL
21760 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f  ECT count(*) FRO
21770 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65  M tab") then the
21780 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
21790 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
217a0 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  ck.** is invoked
217b0 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74   once for that t
217c0 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75  able with a colu
217d0 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20  mn name that is 
217e0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
217f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
21800 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
21810 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
21820 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
21830 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
21840 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
21850 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
21860 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
21870 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
21880 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
21890 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
218a0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
218b0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
218c0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
218d0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
218e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
218f0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
21900 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
21910 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
21920 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
21930 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
21940 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
21950 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
21960 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
21970 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
21980 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
21990 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
219a0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
219b0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
219c0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
219d0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
219e0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
219f0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
21a00 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
21a10 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
21a20 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
21a30 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
21a40 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
21a50 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
21a60 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
21a70 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
21a80 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
21a90 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
21aa0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
21ab0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
21ac0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
21ad0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
21ae0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
21af0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
21b00 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
21b10 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
21b20 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
21b30 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
21b40 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
21b50 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
21b60 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
21b70 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
21b80 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
21b90 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
21ba0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
21bb0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
21bc0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
21bd0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21be0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
21bf0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
21c00 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
21c10 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
21c20 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
21c30 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
21c40 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
21c50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
21c60 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
21c70 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
21c80 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
21c90 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
21ca0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
21cb0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
21cc0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
21cd0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
21ce0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
21cf0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
21d00 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
21d10 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
21d20 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
21d30 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
21d40 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
21d50 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
21d60 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21d70 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
21d80 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
21d90 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
21da0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21db0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
21dc0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21dd0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
21de0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
21df0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
21e00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21e10 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
21e20 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
21e30 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
21e40 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
21e50 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
21e60 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
21e70 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
21e80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
21e90 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
21ea0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
21eb0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
21ec0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
21ed0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
21ee0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
21ef0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
21f00 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
21f10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
21f20 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
21f30 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
21f40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21f50 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
21f60 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
21f70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21f80 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
21f90 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
21fa0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
21fb0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
21fc0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
21fd0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
21fe0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
21ff0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
22000 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
22010 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
22020 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
22030 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
22040 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
22050 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
22060 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
22070 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
22080 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
22090 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
220a0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
220b0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
220c0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
220d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
220e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
220f0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
22100 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
22110 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
22120 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
22130 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
22140 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
22150 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
22160 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22170 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
22180 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
22190 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
221a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
221b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
221c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
221d0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
221e0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
221f0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
22200 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
22210 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
22220 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
22230 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
22240 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
22250 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
22260 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
22270 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
22280 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
22290 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
222a0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
222b0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
222c0 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
222d0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
222e0 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
222f0 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
22300 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
22310 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
22320 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
22330 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
22340 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
22350 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
22360 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
22370 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
22380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22390 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
223a0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
223b0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
223c0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
223d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
223e0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
223f0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
22400 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
22410 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
22420 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
22430 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
22440 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
22450 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
22460 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
22470 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
22480 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
22490 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
224a0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
224b0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
224c0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
224d0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
224e0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
224f0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
22500 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
22510 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
22520 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
22530 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
22540 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
22550 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
22560 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
22570 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
22580 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
22590 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
225a0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
225b0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
225c0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
225d0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
225e0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
225f0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
22600 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
22610 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
22620 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
22630 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
22640 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
22650 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
22660 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
22670 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
22680 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
22690 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
226a0 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
226b0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
226c0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
226d0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
226e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
226f0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
22700 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
22710 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
22720 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
22730 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
22740 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
22750 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
22760 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
22770 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
22780 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
22790 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
227a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
227b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
227c0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
227d0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
227e0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
227f0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
22800 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
22810 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
22820 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22830 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22840 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
22850 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
22860 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22870 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22880 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22890 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
228a0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
228b0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
228c0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
228d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
228e0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
228f0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
22900 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22910 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22920 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22930 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
22940 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
22950 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
22960 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22970 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22980 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
22990 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
229a0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
229b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
229c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
229d0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
229e0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
229f0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22a00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22a10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22a20 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
22a30 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
22a40 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
22a50 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22a60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22a70 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
22a80 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
22a90 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22aa0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22ab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22ac0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
22ad0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
22ae0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
22af0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22b00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22b10 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
22b20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
22b30 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22b40 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22b50 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22b60 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
22b70 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
22b80 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
22b90 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22ba0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22bb0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
22bc0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
22bd0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22be0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22bf0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22c00 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
22c10 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
22c20 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
22c30 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22c40 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
22c50 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
22c60 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
22c70 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22c80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22c90 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
22ca0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
22cb0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22cc0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22cd0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22ce0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
22cf0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
22d00 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
22d10 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22d20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22d30 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
22d40 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
22d50 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22d60 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22d70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22d80 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
22d90 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
22da0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
22db0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
22dc0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
22dd0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
22de0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
22df0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22e00 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
22e10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22e20 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
22e30 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
22e40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22e50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22e60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22e70 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
22e80 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
22e90 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
22ea0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22eb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22ec0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
22ed0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
22ee0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
22ef0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
22f00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22f10 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
22f20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
22f30 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
22f40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22f50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22f60 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
22f70 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
22f80 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
22f90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22fa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
22fb0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
22fc0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
22fd0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
22fe0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22ff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
23000 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
23010 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
23020 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23030 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23040 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
23050 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
23060 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
23070 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
23080 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23090 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
230a0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
230b0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
230c0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
230d0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
230e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
230f0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
23100 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
23110 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
23120 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
23130 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
23140 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
23150 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
23160 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
23170 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
23180 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
23190 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
231a0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
231b0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
231c0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
231d0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
231e0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
231f0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
23200 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
23210 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
23220 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
23230 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
23240 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23250 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
23260 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
23270 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
23280 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
23290 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
232a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
232b0 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73  e deprecated. Us
232c0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
232d0 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  race_v2()] inter
232e0 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20  face.** instead 
232f0 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20  of the routines 
23300 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a  described here..
23310 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
23320 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
23330 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
23340 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
23350 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
23360 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
23370 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
23380 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
23390 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
233a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
233b0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
233c0 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
233d0 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
233e0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
233f0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
23400 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
23410 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23420 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
23430 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
23440 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
23450 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
23460 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
23470 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
23480 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
23490 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
234a0 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
234b0 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
234c0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
234d0 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
234e0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
234f0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
23500 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
23510 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
23520 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
23530 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
23540 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
23550 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
23560 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
23570 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
23580 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
23590 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
235a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
235b0 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
235c0 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
235d0 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
235e0 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
235f0 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
23600 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
23610 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
23620 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
23630 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
23640 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
23650 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
23660 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
23670 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
23680 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
23690 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
236a0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
236b0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
236c0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
236d0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
236e0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
236f0 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
23700 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
23710 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
23720 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
23730 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
23740 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
23750 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
23760 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
23770 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
23780 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
23790 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
237a0 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
237b0 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
237c0 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
237d0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
237e0 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
237f0 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
23800 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
23810 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
23820 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
23830 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
23840 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
23850 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
23860 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
23870 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
23880 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
23890 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
238a0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
238b0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
238c0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
238d0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
238e0 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
238f0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
23900 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  id*);.SQLITE_API
23910 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
23920 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
23930 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
23940 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
23950 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
23960 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
23970 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
23980 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23990 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e  : SQL Trace Even
239a0 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
239b0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43  RDS: SQLITE_TRAC
239c0 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  E.**.** These co
239d0 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79  nstants identify
239e0 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e   classes of even
239f0 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d  ts that can be m
23a00 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e  onitored.** usin
23a10 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  g the [sqlite3_t
23a20 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69  race_v2()] traci
23a30 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d  ng logic.  The M
23a40 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
23a50 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
23a60 32 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61  2(D,M,X,P)] is a
23a70 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  n OR-ed combinat
23a80 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ion of one or mo
23a90 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  re of.** the fol
23aa0 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
23ab0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  .  ^The first ar
23ac0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
23ad0 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
23ae0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  is one of the fo
23af0 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
23b00 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61  s..**.** New tra
23b10 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d  cing constants m
23b20 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
23b30 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
23b40 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
23b50 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72  allback has four
23b60 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c   arguments: xCal
23b70 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
23b80 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
23b90 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
23ba0 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f   integer type co
23bb0 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54  des above..** ^T
23bc0 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
23bd0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
23be0 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70  ontext pointer p
23bf0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
23c00 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  ** fourth argume
23c10 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
23c20 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54  race_v2()]..** T
23c30 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
23c40 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
23c50 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
23c60 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
23c70 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
23c80 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d  LITE_TRACE_STMT]
23c90 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
23ca0 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20  CE_STMT</dt>.** 
23cb0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
23cc0 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61  RACE_STMT callba
23cd0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
23ce0 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74  en a prepared st
23cf0 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74  atement.** first
23d00 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20   begins running 
23d10 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20  and possibly at 
23d20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69  other times duri
23d30 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74  ng the.** execut
23d40 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61  ion of the prepa
23d50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73  red statement, s
23d60 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74  uch as at the st
23d70 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74  art of each.** t
23d80 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
23d90 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  m. ^The P argume
23da0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
23db0 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  to the.** [prepa
23dc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
23dd0 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20  ^The X argument 
23de0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23df0 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a  a string which.*
23e00 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e  * is the unexpan
23e10 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20  ded SQL text of 
23e20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
23e30 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c  tement or an SQL
23e40 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61   comment .** tha
23e50 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20  t indicates the 
23e60 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20  invocation of a 
23e70 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63  trigger.  ^The c
23e80 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70  allback can comp
23e90 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ute.** the same 
23ea0 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20  text that would 
23eb0 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e  have been return
23ec0 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79  ed by the legacy
23ed0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
23ee0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
23ef0 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61  by using the X a
23f00 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62  rgument when X b
23f10 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20  egins with "--" 
23f20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20  and invoking.** 
23f30 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  [sqlite3_expande
23f40 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77  d_sql(P)] otherw
23f50 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ise..**.** [[SQL
23f60 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
23f70 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
23f80 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74  RACE_PROFILE</dt
23f90 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
23fa0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
23fb0 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69  E callback provi
23fc0 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c  des approximatel
23fd0 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e  y the same.** in
23fe0 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20  formation as is 
23ff0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
24000 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
24010 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ()] callback..**
24020 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
24030 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
24040 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24050 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
24060 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
24070 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62  points to a 64-b
24080 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  it integer which
24090 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65   is the estimate
240a0 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  d of.** the numb
240b0 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
240c0 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
240d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  ed statement too
240e0 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68  k to run..** ^Th
240f0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
24100 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
24110 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
24120 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
24130 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  nishes..**.** [[
24140 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
24150 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
24160 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20  ACE_ROW</dt>.** 
24170 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
24180 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63  RACE_ROW callbac
24190 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
241a0 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64  never a prepared
241b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65  .** statement ge
241c0 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65  nerates a single
241d0 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20   row of result. 
241e0 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75   .** ^The P argu
241f0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
24200 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
24210 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
24220 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
24230 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
24240 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
24250 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e  ACE_CLOSE]] <dt>
24260 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
24270 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  SE</dt>.** <dd>^
24280 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
24290 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69  CLOSE callback i
242a0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
242b0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
242c0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
242d0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
242e0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
242f0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
24300 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a   connection] obj
24310 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58  ect.** and the X
24320 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
24330 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  sed..** </dl>.*/
24340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24350 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20  TRACE_STMT      
24360 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51   0x01.#define SQ
24370 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
24380 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69  LE    0x02.#defi
24390 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
243a0 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a  ROW        0x04.
243b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
243c0 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20  RACE_CLOSE      
243d0 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x08../*.** CAPI
243e0 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20  3REF: SQL Trace 
243f0 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Hook.** METHOD: 
24400 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
24410 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
24420 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74  _v2(D,M,X,P) int
24430 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
24440 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63   a trace callbac
24450 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
24460 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73  against [databas
24470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
24480 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20   using property 
24490 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f  mask M.** and co
244a0 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e  ntext pointer P.
244b0 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c    ^If the X call
244c0 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20  back is.** NULL 
244d0 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b  or if the M mask
244e0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   is zero, then t
244f0 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c  racing is disabl
24500 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72  ed.  The.** M ar
24510 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
24520 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d   the bitwise OR-
24530 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
24540 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  f.** zero or mor
24550 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
24560 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
24570 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  * ^Each call to 
24580 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74  either sqlite3_t
24590 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
245a0 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65  3_trace_v2() ove
245b0 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63  rrides .** (canc
245c0 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63  els) any prior c
245d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
245e0 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
245f0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a  e3_trace_v2()..*
24600 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c  *.** ^The X call
24610 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
24620 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20  whenever any of 
24630 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74  the events ident
24640 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73  ified by .** mas
24650 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65  k M occur.  ^The
24660 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20   integer return 
24670 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63  value from the c
24680 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65  allback is curre
24690 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c  ntly.** ignored,
246a0 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79   though this may
246b0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
246c0 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c  e releases.  Cal
246d0 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lback.** impleme
246e0 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
246f0 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65  return zero to e
24700 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d  nsure future com
24710 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
24720 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
24730 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
24740 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  ith four argumen
24750 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43  ts: callback(T,C
24760 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
24770 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
24780 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
24790 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61  TRACE].** consta
247a0 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20  nts to indicate 
247b0 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  why the callback
247c0 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a   was invoked..**
247d0 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74   ^The C argument
247e0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
247f0 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  e context pointe
24800 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  r..** The P and 
24810 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
24820 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
24830 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
24840 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  n T..**.** The s
24850 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24860 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
24870 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61  ntended to repla
24880 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ce the legacy.**
24890 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
248a0 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e  ite3_trace()] an
248b0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d [sqlite3_profi
248c0 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77  le()], both of w
248d0 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72  hich.** are depr
248e0 65 63 61 74 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  ecated..*/.SQLIT
248f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
24900 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71  3_trace_v2(.  sq
24910 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e  lite3*,.  unsign
24920 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28  ed uMask,.  int(
24930 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69  *xCallback)(unsi
24940 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  gned,void*,void*
24950 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20  ,void*),.  void 
24960 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pCtx.);../*.** 
24970 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
24980 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
24990 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
249a0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
249b0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
249c0 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
249d0 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
249e0 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
249f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
24a00 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
24a10 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
24a20 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
24a30 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
24a40 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
24a50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
24a60 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
24a70 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
24a80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24a90 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
24aa0 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
24ab0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
24ac0 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
24ad0 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
24ae0 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
24af0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
24b00 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
24b10 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
24b20 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
24b30 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
24b40 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
24b50 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
24b60 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
24b70 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
24b80 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
24b90 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
24ba0 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
24bb0 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
24bc0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
24bd0 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
24be0 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
24bf0 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
24c00 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
24c10 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
24c20 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
24c30 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
24c40 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
24c50 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
24c60 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
24c70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24c80 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
24c90 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
24ca0 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
24cb0 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
24cc0 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
24cd0 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
24ce0 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
24cf0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
24d00 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
24d10 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
24d20 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
24d30 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
24d40 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
24d50 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
24d60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
24d70 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
24d80 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
24d90 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
24da0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
24db0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
24dc0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
24dd0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
24de0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
24df0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
24e00 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
24e10 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
24e20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
24e30 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
24e40 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
24e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
24e60 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
24e70 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
24e80 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
24e90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
24ea0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
24eb0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
24ec0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
24ed0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24ee0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
24ef0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
24f00 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
24f10 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .**.*/.SQLITE_AP
24f20 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  I void sqlite3_p
24f30 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
24f40 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
24f50 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
24f60 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
24f70 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
24f80 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
24f90 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53  nnection.** CONS
24fa0 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
24fb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
24fc0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
24fd0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
24fe0 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
24ff0 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
25000 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
25010 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
25020 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
25030 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
25040 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
25050 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
25060 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
25070 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
25080 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
25090 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
250a0 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
250b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
250c0 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
250d0 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
250e0 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
250f0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
25100 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
25110 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
25120 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
25130 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
25140 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
25150 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
25160 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
25170 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
25180 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
25190 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
251a0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
251b0 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
251c0 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
251d0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
251e0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
251f0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
25200 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
25210 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
25220 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
25230 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
25240 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
25250 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
25260 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
25270 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
25280 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
25290 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
252a0 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
252b0 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
252c0 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
252d0 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
252e0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
252f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
25300 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
25310 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
25320 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
25330 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
25340 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
25350 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
25360 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
25370 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
25380 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
25390 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
253a0 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
253b0 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
253c0 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
253d0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
253e0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
253f0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
25400 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
25410 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
25420 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
25430 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
25440 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25450 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
25460 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
25470 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
25480 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
25490 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
254a0 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
254b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
254c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
254d0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
254e0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
254f0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
25500 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
25510 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
25520 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
25530 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
25540 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
25550 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25560 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
25570 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
25580 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25590 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
255a0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
255b0 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
255c0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
255d0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
255e0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
255f0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
25600 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
25610 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
25620 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
25630 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
25640 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
25650 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
25660 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
25670 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
25680 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
25690 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
256a0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
256b0 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
256c0 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
256d0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
256e0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
256f0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
25700 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
25710 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
25720 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
25730 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
25740 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
25750 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
25760 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
25770 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
25780 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
25790 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
257a0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
257b0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
257c0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
257d0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
257e0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
257f0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
25800 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
25810 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
25820 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
25830 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
25840 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
25850 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
25860 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
25870 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
25880 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
25890 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
258a0 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
258b0 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
258c0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
258d0 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
258e0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
258f0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
25900 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
25910 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
25920 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
25930 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
25940 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
25950 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25960 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
25970 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
25980 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
25990 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
259a0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
259b0 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
259c0 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
259d0 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
259e0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
259f0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
25a00 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
25a10 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
25a20 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
25a30 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
25a40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25a50 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
25a60 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
25a70 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
25a80 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
25a90 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
25aa0 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
25ab0 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
25ac0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
25ad0 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
25ae0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
25af0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
25b00 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
25b10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25b20 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
25b30 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
25b40 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
25b50 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
25b60 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
25b70 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
25b80 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
25b90 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
25ba0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
25bb0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
25bc0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
25bd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25be0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
25bf0 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
25c00 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
25c10 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
25c20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
25c30 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
25c40 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
25c50 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
25c60 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
25c70 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
25c80 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
25c90 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
25ca0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25cb0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
25cc0 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
25cd0 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
25ce0 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
25cf0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
25d00 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
25d10 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25d20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
25d30 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25d40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
25d50 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
25d60 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
25d70 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
25d80 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
25d90 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
25da0 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
25db0 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
25dc0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
25dd0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
25de0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
25df0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
25e00 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
25e10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
25e20 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
25e30 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
25e40 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
25e50 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
25e60 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
25e70 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
25e80 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
25e90 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25ea0 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
25eb0 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
25ec0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
25ed0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
25ee0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
25ef0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
25f00 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
25f10 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
25f20 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
25f30 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
25f40 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
25f50 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
25f60 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
25f70 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
25f80 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
25f90 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
25fa0 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
25fb0 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
25fc0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
25fd0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
25fe0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
25ff0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
26000 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
26010 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
26020 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
26030 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
26040 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
26050 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
26060 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
26070 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
26080 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
26090 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
260a0 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
260b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
260c0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
260d0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
260e0 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
260f0 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
26100 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
26110 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
26120 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
26130 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
26140 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
26150 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
26160 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
26170 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
26180 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
26190 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
261a0 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
261b0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
261c0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
261d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
261e0 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
261f0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72   in the third ar
26200 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
26210 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
26220 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
26230 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
26240 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
26250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
26260 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
26270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
26280 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
26290 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
262a0 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
262b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
262c0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
262d0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
262e0 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
262f0 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
26300 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
26310 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
26320 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
26330 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
26340 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
26350 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
26360 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
26370 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
26380 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
26390 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
263a0 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
263b0 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
263c0 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
263d0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
263e0 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
263f0 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
26400 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
26410 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
26420 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
26430 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
26440 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
26450 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
26460 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
26470 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
26480 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
26490 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
264a0 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
264b0 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
264c0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
264d0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
264e0 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
264f0 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
26500 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
26510 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
26520 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
26530 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
26540 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
26550 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
26560 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
26570 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
26580 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
26590 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
265a0 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
265b0 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
265c0 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
265d0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
265e0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
265f0 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
26600 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
26610 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
26620 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
26630 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
26640 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
26650 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
26660 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
26670 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
26680 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
26690 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
266a0 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
266b0 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
266c0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
266d0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
266e0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
266f0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
26700 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
26710 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
26720 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
26730 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
26740 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
26750 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
26760 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
26770 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
26780 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
26790 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
267a0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
267b0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
267c0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
267d0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
267e0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
267f0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
26800 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
26810 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
26820 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
26830 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
26840 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
26850 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
26860 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
26870 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
26880 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
26890 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
268a0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
268b0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
268c0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
268d0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
268e0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
268f0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
26900 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
26910 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
26920 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
26930 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
26940 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
26950 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
26960 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
26970 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
26980 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
26990 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
269a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
269b0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
269c0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
269d0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
269e0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
269f0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
26a00 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
26a10 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
26a20 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
26a30 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
26a40 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
26a50 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
26a60 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
26a70 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
26a80 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
26a90 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
26aa0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
26ab0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
26ac0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
26ad0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
26ae0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
26af0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
26b00 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
26b10 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
26b20 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
26b30 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
26b40 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
26b50 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
26b60 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
26b70 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
26b80 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
26b90 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
26ba0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
26bb0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
26bc0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
26bd0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
26be0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
26bf0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
26c00 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
26c10 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
26c20 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
26c30 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
26c40 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
26c50 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
26c60 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
26c70 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
26c80 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
26c90 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
26ca0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
26cb0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
26cc0 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
26cd0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
26ce0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
26cf0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
26d00 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
26d10 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
26d20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
26d30 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
26d40 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
26d50 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
26d60 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
26d70 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
26d80 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
26d90 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
26da0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
26db0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
26dc0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
26dd0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
26de0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
26df0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
26e00 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
26e10 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
26e20 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
26e30 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
26e40 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
26e50 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
26e60 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
26e70 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
26e80 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
26e90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
26ea0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
26eb0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
26ec0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
26ed0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
26ee0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
26ef0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
26f00 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
26f10 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
26f20 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
26f30 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
26f40 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
26f50 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
26f60 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
26f70 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
26f80 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
26f90 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
26fa0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
26fb0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
26fc0 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
26fd0 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
26fe0 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
26ff0 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
27000 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
27010 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
27020 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
27030 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
27040 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
27050 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
27060 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
27070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27080 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
27090 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
270a0 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
270b0 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
270c0 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
270d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
270e0 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
270f0 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
27100 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
27110 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
27120 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
27130 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
27140 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
27150 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
27160 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
27170 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
27180 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
27190 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
271a0 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
271b0 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
271c0 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
271d0 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
271e0 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
271f0 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
27200 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
27210 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
27220 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
27230 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
27240 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
27250 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
27260 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
27270 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
27280 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
27290 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
272a0 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
272b0 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
272c0 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
272d0 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
272e0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
272f0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
27300 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
27310 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
27320 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
27330 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
27340 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
27350 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
27360 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
27370 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
27380 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
27390 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
273a0 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
273b0 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
273c0 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
273d0 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
273e0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
273f0 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
27400 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
27410 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
27420 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
27430 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
27440 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
27450 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
27460 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
27470 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
27480 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
27490 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
274a0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
274b0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
274c0 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
274d0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
274e0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
274f0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
27500 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
27510 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
27520 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
27530 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
27540 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
27550 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
27560 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
27570 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
27580 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
27590 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
275a0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
275b0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
275c0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
275d0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
275e0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
275f0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
27600 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
27610 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
27620 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
27630 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
27640 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
27650 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
27660 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
27670 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
27680 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
27690 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
276a0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
276b0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
276c0 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
276d0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
276e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
276f0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
27700 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27710 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
27720 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
27730 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
27740 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
27750 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
27760 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
27770 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
27780 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
27790 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
277a0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
277b0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
277c0 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
277d0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
277e0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
277f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
27800 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
27810 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
27820 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
27830 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
27840 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
27850 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
27860 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
27870 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
27880 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
27890 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
278a0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
278b0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
278c0 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
278d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
278e0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
278f0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
27900 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
27910 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
27920 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
27930 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
27940 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
27950 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
27960 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
27970 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
27980 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
27990 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
279a0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
279b0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
279c0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
279d0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
279e0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
279f0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
27a00 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
27a10 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
27a20 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
27a30 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
27a40 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
27a50 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
27a60 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
27a70 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
27a80 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
27a90 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
27aa0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
27ab0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
27ac0 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
27ad0 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
27ae0 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
27af0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
27b00 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
27b10 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
27b20 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
27b30 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
27b40 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
27b50 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
27b60 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
27b70 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
27b80 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
27b90 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
27ba0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
27bb0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
27bc0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
27bd0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
27be0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
27bf0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
27c00 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
27c10 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
27c20 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
27c30 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
27c40 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
27c50 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
27c60 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
27c70 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
27c80 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
27c90 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
27ca0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
27cb0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
27cc0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
27cd0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
27ce0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
27cf0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
27d00 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
27d10 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
27d20 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
27d30 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
27d40 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
27d50 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
27d60 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
27d70 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
27d80 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
27d90 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
27da0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
27db0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
27dc0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
27dd0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
27de0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
27df0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
27e00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
27e10 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
27e20 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
27e30 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
27e40 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
27e50 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
27e60 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
27e70 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
27e80 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
27e90 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
27ea0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
27eb0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
27ec0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
27ed0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
27ee0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
27ef0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
27f00 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
27f10 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
27f20 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
27f30 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
27f40 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
27f50 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
27f60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
27f70 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
27f80 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
27f90 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
27fa0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
27fb0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
27fc0 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
27fd0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
27fe0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53  _directory].*/.S
27ff0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
28000 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
28010 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
28020 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
28030 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
28040 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
28050 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
28060 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
28070 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
28080 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
28090 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
280a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
280b0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
280c0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
280d0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
280e0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
280f0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
28100 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
28110 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
28120 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
28130 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
28140 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
28150 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
28160 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
28170 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
28180 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
28190 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
281a0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
281b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
281c0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
281d0 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
281e0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
281f0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
28200 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
28210 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
28220 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
28230 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
28240 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
28250 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
28260 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
28270 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
28280 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
28290 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
282a0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
282b0 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
282c0 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
282d0 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
282e0 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
282f0 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
28300 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
28310 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
28320 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
28330 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
28340 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
28350 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
28360 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
28370 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
28380 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
28390 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
283a0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
283b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
283c0 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
283d0 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
283e0 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
283f0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
28400 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
28410 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
28420 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
28430 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
28440 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
28450 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
28460 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
28470 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
28480 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
28490 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
284a0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
284b0 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
284c0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
284d0 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
284e0 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
284f0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
28500 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
28510 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
28520 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
28530 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
28540 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
28550 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
28560 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
28570 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
28580 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
28590 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
285a0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
285b0 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
285c0 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
285d0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
285e0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
285f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
28600 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
28610 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
28620 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
28630 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
28640 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
28650 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
28660 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
28670 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
28680 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
28690 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
286a0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
286b0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
286c0 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
286d0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
286e0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
286f0 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
28700 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
28710 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
28720 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
28730 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
28740 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
28750 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
28760 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
28770 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
28780 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
28790 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
287a0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
287b0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
287c0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
287d0 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
287e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
287f0 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
28800 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
28810 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
28820 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
28830 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
28840 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
28850 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
28860 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
28870 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
28880 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
28890 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
288a0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
288b0 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
288c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
288d0 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
288e0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
288f0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
28900 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
28910 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
28920 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
28930 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
28940 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
28950 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
28960 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
28970 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
28980 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
28990 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
289a0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
289b0 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
289c0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
289d0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
289e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
289f0 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
28a00 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51  desirable..*/.SQ
28a10 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
28a20 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
28a30 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
28a40 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
28a50 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
28a60 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50  aram);.SQLITE_AP
28a70 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  I int sqlite3_ur
28a80 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
28a90 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
28aa0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
28ab0 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
28ac0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
28ad0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
28ae0 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
28af0 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
28b00 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
28b10 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
28b20 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
28b30 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
28b40 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28b50 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
28b60 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
28b70 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
28b80 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
28b90 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
28ba0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
28bb0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
28bc0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
28bd0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
28be0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
28bf0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
28c00 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
28c10 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
28c20 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
28c30 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
28c40 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
28c50 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
28c60 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
28c70 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
28c80 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
28c90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
28ca0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
28cb0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
28cc0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
28cd0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
28ce0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
28cf0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
28d00 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
28d10 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
28d20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
28d30 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
28d40 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
28d50 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
28d60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
28d70 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
28d80 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
28d90 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
28da0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
28db0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
28dc0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
28dd0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
28de0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
28df0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
28e00 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
28e10 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
28e20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
28e30 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
28e40 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
28e50 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
28e60 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
28e70 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
28e80 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
28e90 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
28ea0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
28eb0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
28ec0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
28ed0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
28ee0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
28ef0 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
28f00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28f10 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
28f20 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
28f30 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
28f40 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
28f50 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
28f60 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
28f70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
28f80 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
28f90 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
28fa0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
28fb0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
28fc0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
28fd0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
28fe0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
28ff0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
29000 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
29010 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
29020 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
29030 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
29040 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
29050 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
29060 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
29070 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
29080 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
29090 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
290a0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
290b0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
290c0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
290d0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
290e0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
290f0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
29100 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
29110 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
29120 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
29130 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
29140 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
29150 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29160 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
29170 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
29180 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
29190 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
291a0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
291b0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
291c0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
291d0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
291e0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
291f0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
29200 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
29210 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
29220 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
29230 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
29240 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
29250 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
29260 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
29270 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
29280 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
29290 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
292a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
292b0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
292c0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
292d0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
292e0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
292f0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
29300 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72   int sqlite3_err
29310 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
29320 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
29330 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
29340 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
29350 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
29360 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
29370 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
29380 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
29390 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
293a0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
293b0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  6(sqlite3*);.SQL
293c0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
293d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
293e0 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
293f0 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
29400 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
29410 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
29420 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
29430 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
29440 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
29450 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
29460 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
29470 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
29480 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
29490 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  hat.** has been 
294a0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69  compiled into bi
294b0 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73  nary form and is
294c0 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61   ready to be eva
294d0 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  luated..**.** Th
294e0 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20  ink of each SQL 
294f0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73  statement as a s
29500 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72  eparate computer
29510 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a   program.  The.*
29520 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
29530 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f  ext is source co
29540 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20  de.  A prepared 
29550 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
29560 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70   .** is the comp
29570 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65  iled object code
29580 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20  .  All SQL must 
29590 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  be converted int
295a0 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  o a.** prepared 
295b0 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65  statement before
295c0 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a   it can be run..
295d0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63  **.** The life-c
295e0 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72  ycle of a prepar
295f0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
29600 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73  ect usually goes
29610 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
29620 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
29630 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72  reate the prepar
29640 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
29650 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
29660 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29670 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
29680 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65  alues to [parame
29690 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
296a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
296b0 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
296c0 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
296d0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
296e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
296f0 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
29700 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
29710 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  Reset the prepar
29720 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
29730 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
29740 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
29750 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
29760 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
29770 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
29780 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
29790 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
297a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
297b0 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
297c0 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  >.*/.typedef str
297d0 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
297e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
297f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29800 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
29810 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
29820 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e3.**.** ^(This 
29830 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
29840 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
29850 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
29860 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
29870 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
29880 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
29890 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
298a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
298b0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
298c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
298d0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
298e0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
298f0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
29900 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
29910 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
29920 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
29930 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
29940 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
29950 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
29960 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
29970 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
29980 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
29990 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
299a0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
299b0 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
299c0 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
299d0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
299e0 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
299f0 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
29a00 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
29a10 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
29a20 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
29a30 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
29a40 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
29a50 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
29a60 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
29a70 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
29a80 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
29a90 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
29aa0 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
29ab0 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
29ac0 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
29ad0 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
29ae0 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
29af0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
29b00 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
29b10 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
29b20 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
29b30 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
29b40 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
29b50 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
29b60 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
29b70 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
29b80 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
29b90 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
29ba0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
29bb0 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
29bc0 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
29bd0 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
29be0 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
29bf0 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
29c00 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
29c10 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
29c20 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
29c30 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
29c40 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
29c50 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
29c60 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
29c70 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
29c80 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
29c90 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
29ca0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
29cb0 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
29cc0 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
29cd0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
29ce0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
29cf0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
29d00 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
29d10 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
29d20 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
29d30 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
29d40 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
29d50 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
29d60 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
29d70 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
29d80 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
29d90 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
29da0 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
29db0 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
29dc0 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
29dd0 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
29de0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
29df0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
29e00 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
29e10 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
29e20 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
29e30 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
29e40 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
29e50 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
29e60 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
29e70 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
29e80 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
29e90 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
29ea0 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
29eb0 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
29ec0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
29ed0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
29ee0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
29ef0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
29f00 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
29f10 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
29f20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
29f30 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
29f40 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
29f50 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
29f60 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
29f70 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
29f80 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
29f90 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
29fa0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
29fb0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
29fc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
29fd0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
29fe0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
29ff0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
2a000 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
2a010 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
2a020 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
2a030 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
2a040 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
2a050 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
2a060 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
2a070 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
2a080 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
2a090 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
2a0a0 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
2a0b0 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
2a0c0 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
2a0d0 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
2a0e0 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
2a0f0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
2a100 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
2a110 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
2a120 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2a130 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
2a140 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
2a150 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
2a160 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
2a170 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
2a180 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a190 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
2a1a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a1b0 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
2a1c0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
2a1d0 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
2a1e0 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
2a1f0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a200 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
2a210 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a220 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
2a230 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2a240 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
2a250 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
2a260 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
2a270 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a280 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
2a290 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a2a0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
2a2b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a2c0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2a2d0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
2a2e0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
2a2f0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
2a300 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
2a310 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
2a320 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2a330 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
2a340 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
2a350 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
2a360 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
2a370 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a380 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
2a390 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a3a0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
2a3b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2a3c0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
2a3d0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
2a3e0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
2a3f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a400 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2a410 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
2a420 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
2a430 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
2a440 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a450 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2a460 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
2a470 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
2a480 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
2a490 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a4a0 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
2a4b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a4c0 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
2a4d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a4e0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
2a4f0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
2a500 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
2a510 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
2a520 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
2a530 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b  statement.  If [
2a540 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a550 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20  v2()] or.** the 
2a560 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73  equivalent tries
2a570 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61   to allocate spa
2a580 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e  ce for more than
2a590 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64   this many opcod
2a5a0 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c  es.** in a singl
2a5b0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2a5c0 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f  ment, an SQLITE_
2a5d0 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72  NOMEM error is r
2a5e0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
2a5f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a600 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2a610 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
2a620 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2a630 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
2a640 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2a650 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2a660 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
2a670 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a680 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
2a690 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
2a6a0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
2a6b0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
2a6c0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a6d0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
2a6e0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
2a6f0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
2a700 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
2a710 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2a720 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
2a730 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
2a740 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
2a750 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a760 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2a770 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
2a780 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
2a790 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
2a7a0 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
2a7b0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a7c0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2a7d0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
2a7e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a7f0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
2a800 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a810 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
2a820 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
2a830 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
2a840 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
2a850 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a860 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
2a870 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2a880 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
2a890 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
2a8a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
2a8b0 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
2a8c0 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
2a8d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a8e0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
2a8f0 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
2a900 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
2a910 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
2a920 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a930 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
2a940 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
2a950 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
2a960 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
2a970 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
2a980 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
2a990 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
2a9a0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a9b0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
2a9c0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
2a9d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a9e0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
2a9f0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
2aa00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2aa10 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
2aa20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
2aa30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2aa40 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
2aa50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
2aa60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2aa70 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2aa80 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
2aa90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2aaa0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
2aab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2aac0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
2aad0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2aae0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
2aaf0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
2ab00 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2ab10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ab20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
2ab30 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2ab40 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
2ab50 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
2ab60 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2ab70 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
2ab80 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
2ab90 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2aba0 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
2abb0 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
2abc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2abd0 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
2abe0 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
2abf0 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
2ac00 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
2ac10 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
2ac20 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67  ine various flag
2ac30 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61  s that can be pa
2ac40 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72  ssed into.** "pr
2ac50 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74  epFlags" paramet
2ac60 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  er of the [sqlit
2ac70 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2ac80 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2ac90 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2aca0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a   interfaces..**.
2acb0 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79  ** New flags may
2acc0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
2acd0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
2ace0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64  SQLite..**.** <d
2acf0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50  l>.** [[SQLITE_P
2ad00 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2ad10 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
2ad20 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2ad30 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ENT</dt>.** <dd>
2ad40 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  The SQLITE_PREPA
2ad50 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c  RE_PERSISTENT fl
2ad60 61 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20  ag is a hint to 
2ad70 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  the query planne
2ad80 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2ad90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ada0 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65   will be retaine
2adb0 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d  d for a long tim
2adc0 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c  e and.** probabl
2add0 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69  y reused many ti
2ade0 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20  mes.)^ ^Without 
2adf0 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69  this flag, [sqli
2ae00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2ae10 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2ae20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2ae30 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68  ] assume that th
2ae40 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2ae50 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65  ment will .** be
2ae60 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20   used just once 
2ae70 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77  or at most a few
2ae80 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20   times and then 
2ae90 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
2aea0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2aeb0 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65  lize()] relative
2aec0 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72  ly soon. The cur
2aed0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
2aee0 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74  ion acts.** on t
2aef0 68 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69  his hint by avoi
2af00 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20  ding the use of 
2af10 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
2af20 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a  y] so as not to.
2af30 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c  ** deplete the l
2af40 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20  imited store of 
2af50 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
2af60 2e 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e  . Future version
2af70 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  s of.** SQLite m
2af80 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68  ay act on this h
2af90 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e  int differently.
2afa0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
2afb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50  fine SQLITE_PREP
2afc0 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20  ARE_PERSISTENT  
2afd0 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 31              0x01
2afe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2aff0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
2b000 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2b010 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
2b020 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
2b030 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
2b040 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55  lite3.** CONSTRU
2b050 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
2b060 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  mt.**.** To exec
2b070 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ute an SQL state
2b080 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69  ment, it must fi
2b090 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
2b0a0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
2b0b0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
2b0c0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
2b0d0 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e  outines.  Or, in
2b0e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2b0f0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2b100 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  are constructors
2b110 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2b120 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
2b130 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ject..**.** The 
2b140 70 72 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e  preferred routin
2b150 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c  e to use is [sql
2b160 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b170 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  )].  The.** [sql
2b180 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2b190 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65 67  interface is leg
2b1a0 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62  acy and should b
2b1b0 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73  e avoided..** [s
2b1c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b1d0 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72  3()] has an extr
2b1e0 61 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70  a "prepFlags" op
2b1f0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65  tion that is use
2b200 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c  d.** for special
2b210 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
2b220 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2b230 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73  UTF-8 interfaces
2b240 20 69 73 20 70 72 65 66 65 72 72 65 64 2c 20 61   is preferred, a
2b250 73 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74  s SQLite current
2b260 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70  ly.** does all p
2b270 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46  arsing using UTF
2b280 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20  -8.  The UTF-16 
2b290 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
2b2a0 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20  rovided.** as a 
2b2b0 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68  convenience.  Th
2b2c0 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61  e UTF-16 interfa
2b2d0 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76  ces work by conv
2b2e0 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e  erting the.** in
2b2f0 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54  put text into UT
2b300 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69  F-8, then invoki
2b310 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ng the correspon
2b320 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72  ding UTF-8 inter
2b330 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
2b340 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
2b350 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
2b360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b370 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
2b380 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
2b390 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2b3a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2b3b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2b3c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2b3d0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
2b3e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2b3f0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
2b400 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
2b410 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2b420 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
2b430 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
2b440 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2b450 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
2b460 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
2b470 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
2b480 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2b490 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2b4a0 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  re_v2(),.** and 
2b4b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b4c0 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v3().** interfac
2b4d0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
2b4e0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2b4f0 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  e16(), sqlite3_p
2b500 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2b510 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2b520 65 70 61 72 65 31 36 5f 76 33 28 29 20 75 73 65  epare16_v3() use
2b530 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
2b540 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
2b550 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
2b560 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
2b570 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
2b580 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
2b590 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
2b5a0 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
2b5b0 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
2b5c0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2b5d0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
2b5e0 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
2b5f0 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
2b600 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2b610 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
2b620 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
2b630 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
2b640 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
2b650 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
2b660 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
2b670 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
2b680 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
2b690 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
2b6a0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
2b6b0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
2b6c0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2b6d0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
2b6e0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
2b6f0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
2b700 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
2b710 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
2b720 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
2b730 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
2b740 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
2b750 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
2b760 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
2b770 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
2b780 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
2b790 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2b7a0 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
2b7b0 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
2b7c0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
2b7d0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
2b7e0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
2b7f0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
2b800 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
2b810 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
2b820 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
2b830 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
2b840 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
2b850 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
2b860 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b870 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
2b880 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
2b890 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
2b8a0 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
2b8b0 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
2b8c0 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
2b8d0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
2b8e0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
2b8f0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
2b900 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
2b910 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
2b920 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
2b930 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
2b940 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
2b950 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
2b960 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
2b970 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2b980 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
2b990 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
2b9a0 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
2b9b0 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
2b9c0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
2b9d0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
2b9e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
2b9f0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
2ba00 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2ba10 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
2ba20 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
2ba30 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
2ba40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2ba50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c  e3_prepare_v2(),
2ba60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2ba70 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  _v3(), sqlite3_p
2ba80 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2ba90 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2baa0 65 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74  epare16_v3() int
2bab0 65 72 66 61 63 65 73 20 61 72 65 20 72 65 63 6f  erfaces are reco
2bac0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
2bad0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a  new programs..**
2bae0 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72   The older inter
2baf0 66 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70  faces (sqlite3_p
2bb00 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
2bb10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2bb20 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65  ).** are retaine
2bb30 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
2bb40 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
2bb50 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
2bb60 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
2bb70 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74  ^In the "vX" int
2bb80 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
2bb90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2bba0 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
2bbb0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
2bbc0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
2bbd0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
2bbe0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
2bbf0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
2bc00 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
2bc10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
2bc20 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
2bc30 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
2bc40 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
2bc50 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2bc60 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
2bc70 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
2bc80 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
2bc90 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
2bca0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
2bcb0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
2bcc0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
2bcd0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
2bce0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2bcf0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
2bd00 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2bd10 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
2bd20 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
2bd30 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
2bd40 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
2bd50 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
2bd60 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
2bd70 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
2bd80 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
2bd90 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
2bda0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
2bdb0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
2bdc0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2bdd0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
2bde0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
2bdf0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
2be00 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
2be10 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
2be20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
2be30 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
2be40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2be50 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
2be60 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
2be70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
2be80 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
2be90 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2bea0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
2beb0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
2bec0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2bed0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
2bee0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
2bef0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
2bf00 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
2bf10 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
2bf20 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
2bf30 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
2bf40 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
2bf50 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
2bf60 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
2bf70 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2bf80 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2bf90 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
2bfa0 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
2bfb0 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
2bfc0 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
2bfd0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
2bfe0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2bff0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2c000 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
2c010 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
2c020 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
2c030 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
2c040 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
2c050 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
2c060 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
2c070 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
2c080 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
2c090 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
2c0a0 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
2c0b0 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
2c0c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
2c0d0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
2c0e0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
2c0f0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
2c100 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
2c110 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
2c120 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
2c130 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
2c140 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2c150 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2c160 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
2c170 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
2c180 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
2c190 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
2c1a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2c1b0 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
2c1c0 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
2c1d0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
2c1e0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
2c1f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2c200 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
2c210 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
2c220 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69  >.**.** <p>^sqli
2c230 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2c240 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20 73 71   differs from sq
2c250 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c260 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76 69 6e  () only in havin
2c270 67 0a 2a 2a 20 74 68 65 20 65 78 74 72 61 20 70  g.** the extra p
2c280 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74  repFlags paramet
2c290 65 72 2c 20 77 68 69 63 68 20 69 73 20 61 20 62  er, which is a b
2c2a0 69 74 20 61 72 72 61 79 20 63 6f 6e 73 69 73 74  it array consist
2c2b0 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a  ing of zero or.*
2c2c0 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
2c2d0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2c2e0 52 53 49 53 54 45 4e 54 7c 53 51 4c 49 54 45 5f  RSISTENT|SQLITE_
2c2f0 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61 67 73  PREPARE_*] flags
2c300 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
2c310 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
2c320 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
2c330 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
2c340 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70   as.** sqlite3_p
2c350 72 65 70 61 72 65 5f 76 33 28 29 20 77 69 74 68  repare_v3() with
2c360 20 61 20 7a 65 72 6f 20 70 72 65 70 46 6c 61 67   a zero prepFlag
2c370 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2f 0a  s parameter..*/.
2c380 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2c390 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
2c3a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2c3b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2c3c0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2c3d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2c3e0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2c3f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2c400 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2c410 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2c420 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2c430 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2c440 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2c450 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2c460 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2c470 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2c480 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c490 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2c4a0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2c4b0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2c4c0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
2c4d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2c4e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c4f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2c500 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2c510 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2c520 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2c530 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2c540 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2c550 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2c560 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2c570 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2c580 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2c590 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2c5a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2c5b0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2c5c0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2c5d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2c5e0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2c5f0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2c600 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2c610 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
2c620 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2c630 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2c640 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2c650 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2c660 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2c670 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2c680 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2c690 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2c6a0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2c6b0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2c6c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2c6d0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2c6e0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2c6f0 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70    unsigned int p
2c700 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72  repFlags, /* Zer
2c710 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45  o or more SQLITE
2c720 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20  _PREPARE_ flags 
2c730 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2c740 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2c750 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2c760 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c770 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2c780 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2c790 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2c7a0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2c7b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2c7c0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2c7d0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
2c7e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2c7f0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2c800 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2c810 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2c820 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2c830 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2c840 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2c850 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c860 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2c870 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2c880 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2c890 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2c8a0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2c8b0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c8c0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2c8d0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2c8e0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2c8f0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2c900 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
2c910 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2c920 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
2c930 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2c940 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2c950 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c960 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2c970 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2c980 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2c990 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2c9a0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2c9b0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2c9c0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2c9d0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2c9e0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2c9f0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2ca00 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2ca10 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2ca20 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2ca30 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2ca40 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2ca50 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
2ca60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
2ca70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73  repare16_v3(.  s
2ca80 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2ca90 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2caa0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2cab0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2cac0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2cad0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2cae0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2caf0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2cb00 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2cb10 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2cb20 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e  n bytes. */.  un
2cb30 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46  signed int prepF
2cb40 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72  lags, /* Zero or
2cb50 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45   more SQLITE_PRE
2cb60 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20  PARE_ flags */. 
2cb70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2cb80 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2cb90 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2cba0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2cbb0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2cbc0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2cbd0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2cbe0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
2cbf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cc00 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
2cc10 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48  ment SQL.** METH
2cc20 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2cc30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2cc40 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  te3_sql(P) inter
2cc50 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2cc60 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79  ointer to a copy
2cc70 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a   of the UTF-8.**
2cc80 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
2cc90 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72  o create [prepar
2cca0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20  ed statement] P 
2ccb0 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61  if P was.** crea
2ccc0 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2ccd0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2cce0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ccf0 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
2cd00 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2cd10 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
2cd20 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e  prepare16_v3()].
2cd30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cd40 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2cd50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2cd60 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2cd70 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2cd80 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2cd90 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65   SQL text of pre
2cda0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2cdb0 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64  P with.** [bound
2cdc0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70   parameters] exp
2cdd0 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  anded..**.** ^(F
2cde0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2cdf0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ce00 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75  ent is created u
2ce10 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20  sing the SQL.** 
2ce20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62  text "SELECT $ab
2ce30 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70  c,:xyz" and if p
2ce40 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73  arameter $abc is
2ce50 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65   bound to intege
2ce60 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61  r 2345.** and pa
2ce70 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20  rameter :xyz is 
2ce80 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71  unbound, then sq
2ce90 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c  lite3_sql() will
2cea0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f   return.** the o
2ceb0 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20  riginal string, 
2cec0 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2ced0 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65  z" but sqlite3_e
2cee0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a  xpanded_sql().**
2cef0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45   will return "SE
2cf00 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e  LECT 2345,NULL".
2cf10 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2cf20 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2cf30 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ql() interface r
2cf40 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
2cf50 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
2cf60 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62  ry.** is availab
2cf70 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  le to hold the r
2cf80 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65  esult, or if the
2cf90 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78   result would ex
2cfa0 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20  ceed the.** the 
2cfb0 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c  maximum string l
2cfc0 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64  ength determined
2cfd0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
2cfe0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  LIMIT_LENGTH]..*
2cff0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
2d000 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
2d010 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
2d020 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74   option limits t
2d030 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f  he size of.** bo
2d040 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 78  und parameter ex
2d050 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20  pansions.  ^The 
2d060 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41  [SQLITE_OMIT_TRA
2d070 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
2d080 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65  .** option cause
2d090 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  s sqlite3_expand
2d0a0 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61  ed_sql() to alwa
2d0b0 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  ys return NULL..
2d0c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  **.** ^The strin
2d0d0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2d0e0 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20  lite3_sql(P) is 
2d0f0 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74  managed by SQLit
2d100 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f  e and is.** auto
2d110 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2d120 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  when the prepare
2d130 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66  d statement is f
2d140 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68  inalized..** ^Th
2d150 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2d160 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70  d by sqlite3_exp
2d170 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e  anded_sql(P), on
2d180 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
2d190 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20  .** is obtained 
2d1a0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2d1b0 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74  lloc()] and must
2d1c0 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20   be free by the 
2d1d0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62  application.** b
2d1e0 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  y passing it to 
2d1f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2d200 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2d210 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2d220 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
2d230 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 53 51  stmt *pStmt);.SQ
2d240 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
2d250 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2d260 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2d270 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2d280 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2d290 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
2d2a0 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
2d2b0 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20  The Database.** 
2d2c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2d2d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2d2e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2d2f0 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
2d300 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2d310 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
2d320 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
2d330 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d340 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
2d350 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
2d360 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
2d370 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2d380 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
2d390 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
2d3a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2d3b0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
2d3c0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
2d3d0 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
2d3e0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
2d3f0 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
2d400 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
2d410 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2d420 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2d430 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
2d440 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
2d450 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
2d460 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
2d470 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2d480 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
2d490 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
2d4a0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
2d4b0 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
2d4c0 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
2d4d0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
2d4e0 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
2d4f0 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
2d500 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
2d510 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2d520 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
2d530 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
2d540 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2d550 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
2d560 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
2d570 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
2d580 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d590 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
2d5a0 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
2d5b0 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
2d5c0 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
2d5d0 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
2d5e0 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
2d5f0 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
2d600 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
2d610 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
2d620 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2d630 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2d640 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
2d650 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
2d660 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
2d670 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
2d680 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
2d690 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
2d6a0 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
2d6b0 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
2d6c0 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
2d6d0 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
2d6e0 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
2d6f0 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
2d700 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
2d710 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
2d720 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d730 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2d740 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
2d750 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
2d760 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
2d770 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
2d780 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d790 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
2d7a0 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
2d7b0 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
2d7c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2d7d0 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
2d7e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d7f0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2d800 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d810 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49  s true for [BEGI
2d820 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47  N] since.** [BEG
2d830 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20  IN] merely sets 
2d840 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20  internal flags, 
2d850 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42  but the [BEGIN|B
2d860 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20  EGIN IMMEDIATE] 
2d870 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45  and.** [BEGIN|BE
2d880 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63  GIN EXCLUSIVE] c
2d890 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68  ommands do touch
2d8a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
2d8b0 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d so.** sqlite3_
2d8c0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2d8d0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f  returns false fo
2d8e0 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73  r those commands
2d8f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2d900 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2d910 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
2d920 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2d930 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d940 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
2d950 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2d960 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
2d970 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2d980 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2d990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2d9a0 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
2d9b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2d9c0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
2d9d0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2d9e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
2d9f0 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
2da00 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
2da10 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
2da20 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
2da30 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63  neither run to c
2da40 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72  ompletion (retur
2da50 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ned.** [SQLITE_D
2da60 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ONE] from [sqlit
2da70 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72  e3_step(S)]) nor
2da80 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
2da90 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
2daa0 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
2dab0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2dac0 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
2dad0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
2dae0 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
2daf0 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
2db00 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
2db10 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
2db20 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
2db30 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
2db40 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2db50 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
2db60 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2db70 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2db80 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
2db90 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
2dba0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2dbb0 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
2dbc0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2dbd0 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
2dbe0 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
2dbf0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
2dc00 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
2dc10 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
2dc20 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
2dc30 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
2dc40 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
2dc50 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
2dc60 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
2dc70 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
2dc80 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
2dc90 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
2dca0 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
2dcb0 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
2dcc0 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51  tion open..*/.SQ
2dcd0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2dce0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
2dcf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2dd00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2dd10 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
2dd20 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
2dd30 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
2dd40 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2dd50 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
2dd60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2dd70 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
2dd80 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
2dd90 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
2dda0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
2ddb0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
2ddc0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
2ddd0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
2dde0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2ddf0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
2de00 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
2de10 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
2de20 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
2de30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2de40 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
2de50 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
2de60 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
2de70 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
2de80 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
2de90 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2dea0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
2deb0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
2dec0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
2ded0 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
2dee0 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
2def0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2df00 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
2df10 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
2df20 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
2df30 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
2df40 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2df50 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
2df60 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
2df70 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
2df80 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
2df90 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
2dfa0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
2dfb0 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
2dfc0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2dfd0 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  lue.  The.** [sq
2dfe0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2dff0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2e000 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   be used to cons
2e010 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20  truct a new .** 
2e020 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e030 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20  3_value from an 
2e040 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e050 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
2e060 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
2e070 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
2e080 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
2e090 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
2e0a0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
2e0b0 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
2e0c0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
2e0d0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
2e0e0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e0f0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
2e100 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2e110 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
2e120 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e130 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
2e140 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
2e150 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
2e160 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
2e170 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2e180 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
2e190 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2e1a0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
2e1b0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
2e1c0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
2e1d0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
2e1e0 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
2e1f0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2e200 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
2e210 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2e220 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
2e230 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
2e240 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2e250 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2e260 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2e270 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2e280 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
2e290 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
2e2a0 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
2e2b0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
2e2c0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
2e2d0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
2e2e0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
2e2f0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
2e300 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
2e310 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2e320 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2e330 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e340 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
2e350 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
2e360 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
2e370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e380 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e390 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
2e3a0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
2e3b0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
2e3c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
2e3d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e3e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2e3f0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
2e400 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e410 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
2e420 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2e430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2e440 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
2e450 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
2e460 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e470 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
2e480 6c 79 20 62 65 20 75 73 65 64 20 61 73 20 61 72  ly be used as ar
2e490 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73  guments.** to [s
2e4a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2e4b0 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lue()], [sqlite3
2e4c0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2c 20  _bind_value()], 
2e4d0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2e4e0 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a  value_dup()]..**
2e4f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2e500 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
2e510 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
2e520 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
2e530 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2e540 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2e550 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e560 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2e570 75 63 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  uct sqlite3_valu
2e580 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  e sqlite3_value;
2e590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e5a0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
2e5b0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
2e5c0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
2e5d0 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
2e5e0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
2e5f0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
2e600 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
2e610 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
2e620 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
2e630 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2e640 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
2e650 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
2e660 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
2e670 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2e680 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
2e690 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2e6a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2e6b0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2e6c0 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
2e6d0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
2e6e0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
2e6f0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
2e700 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
2e710 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
2e720 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2e730 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
2e740 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2e750 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2e760 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2e770 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
2e780 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
2e790 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
2e7a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
2e7b0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2e7c0 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
2e7d0 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
2e7e0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
2e7f0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
2e800 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
2e810 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
2e820 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
2e830 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
2e840 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
2e850 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2e860 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2e870 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
2e880 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
2e890 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
2e8a0 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ng}.** METHOD: s
2e8b0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2e8c0 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
2e8d0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
2e8e0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
2e8f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2e900 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
2e910 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
2e920 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
2e930 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
2e940 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
2e950 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
2e960 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
2e970 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
2e980 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
2e990 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
2e9a0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
2e9b0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
2e9c0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
2e9d0 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
2e9e0 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
2e9f0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
2ea00 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
2ea10 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
2ea20 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
2ea30 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
2ea40 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
2ea50 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
2ea60 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
2ea70 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
2ea80 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
2ea90 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
2eaa0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2eab0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2eac0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
2ead0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2eae0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2eaf0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2eb00 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
2eb10 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
2eb20 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
2eb30 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2eb40 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
2eb50 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2eb60 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
2eb70 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
2eb80 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2eb90 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2eba0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
2ebb0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
2ebc0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
2ebd0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
2ebe0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2ebf0 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
2ec00 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
2ec10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
2ec20 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
2ec30 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
2ec40 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
2ec50 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
2ec60 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
2ec70 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
2ec80 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
2ec90 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
2eca0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
2ecb0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
2ecc0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
2ecd0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2ece0 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
2ecf0 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
2ed00 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
2ed10 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
2ed20 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
2ed30 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
2ed40 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
2ed50 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
2ed60 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
2ed70 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
2ed80 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2ed90 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
2eda0 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
2edb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2edc0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2edd0 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
2ede0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2edf0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
2ee00 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2ee10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2ee20 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2ee30 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2ee40 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2ee50 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
2ee60 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
2ee70 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2ee80 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
2ee90 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
2eea0 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
2eeb0 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
2eec0 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
2eed0 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
2eee0 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
2eef0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
2ef00 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
2ef10 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2ef20 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
2ef30 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
2ef40 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
2ef50 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2ef60 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
2ef70 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
2ef80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2ef90 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
2efa0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2efb0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2efc0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2efd0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2efe0 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
2eff0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2f000 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2f010 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2f020 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2f030 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2f040 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2f050 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
2f060 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2f070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f080 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
2f090 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
2f0a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2f0b0 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
2f0c0 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
2f0d0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
2f0e0 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
2f0f0 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
2f100 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f110 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74  ext16() or sqlit
2f120 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2f130 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61   then.** that pa
2f140 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2f150 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
2f160 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
2f170 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
2f180 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
2f190 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
2f1a0 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
2f1b0 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
2f1c0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
2f1d0 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
2f1e0 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
2f1f0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2f200 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2f210 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2f220 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
2f230 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
2f240 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
2f250 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
2f260 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
2f270 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
2f280 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
2f290 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
2f2a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
2f2b0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
2f2c0 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e  e BLOB and strin
2f2d0 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66  g binding interf
2f2e0 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73  aces.** is a des
2f2f0 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
2f300 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2f310 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
2f320 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
2f330 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2f340 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
2f350 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
2f360 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
2f370 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2f380 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
2f390 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20  all to bind API 
2f3a0 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  fails..** ^If th
2f3b0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2f3c0 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
2f3d0 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
2f3e0 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
2f3f0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2f400 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
2f410 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
2f420 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
2f430 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2f440 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
2f450 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
2f460 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
2f470 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
2f480 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
2f490 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
2f4a0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
2f4b0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2f4c0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
2f4d0 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
2f4e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2f4f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2f500 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ..**.** ^The six
2f510 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2f520 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f530 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  64() must be one
2f540 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   of.** [SQLITE_U
2f550 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2f560 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
2f570 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
2f580 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74  TE_UTF16LE].** t
2f590 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e  o specify the en
2f5a0 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65  coding of the te
2f5b0 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  xt in the third 
2f5c0 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a  parameter.  If.*
2f5d0 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75  * the sixth argu
2f5e0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2f5f0 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73  bind_text64() is
2f600 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
2f610 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  ** allowed value
2f620 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f  s shown above, o
2f630 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e  r if the text en
2f640 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2f650 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ent.** from the 
2f660 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2f670 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20  ed by the sixth 
2f680 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
2f690 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2f6a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2f6b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f6c0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
2f6d0 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
2f6e0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
2f6f0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
2f700 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
2f710 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
2f720 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
2f730 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
2f740 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
2f750 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
2f760 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
2f770 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
2f780 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
2f790 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
2f7a0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
2f7b0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
2f7c0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
2f7d0 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
2f7e0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2f7f0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
2f800 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
2f810 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
2f820 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
2f830 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
2f840 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
2f850 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
2f860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f870 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
2f880 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f 75 74  (S,I,P,T,D) rout
2f890 69 6e 65 20 63 61 75 73 65 73 20 74 68 65 20 49  ine causes the I
2f8a0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e  -th parameter in
2f8b0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2f8c0 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 68 61  atement] S to ha
2f8d0 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75 65 20  ve an SQL value 
2f8e0 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74 6f 20  of NULL, but to 
2f8f0 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73 6f 63  also be.** assoc
2f900 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
2f910 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79 70 65  ointer P of type
2f920 20 54 2e 20 20 5e 44 20 69 73 20 65 69 74 68 65   T.  ^D is eithe
2f930 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
2f940 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72   or.** a pointer
2f950 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72   to a destructor
2f960 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 50 2e   function for P.
2f970 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e   ^SQLite will in
2f980 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65 73 74  voke the.** dest
2f990 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20  ructor D with a 
2f9a0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
2f9b0 6f 66 20 50 20 77 68 65 6e 20 69 74 20 69 73 20  of P when it is 
2f9c0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a  finished using.*
2f9d0 2a 20 50 2e 20 20 54 68 65 20 54 20 70 61 72 61  * P.  The T para
2f9e0 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
2f9f0 61 20 73 74 61 74 69 63 20 73 74 72 69 6e 67 2c  a static string,
2fa00 20 70 72 65 66 65 72 61 62 6c 79 20 61 20 73 74   preferably a st
2fa10 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e  ring.** literal.
2fa20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
2fa30 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 74  d_pointer() rout
2fa40 69 6e 65 20 69 73 20 70 61 72 74 20 6f 66 20 74  ine is part of t
2fa50 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72 20 70  he.** [pointer p
2fa60 61 73 73 69 6e 67 20 69 6e 74 65 72 66 61 63 65  assing interface
2fa70 5d 20 61 64 64 65 64 20 66 6f 72 20 53 51 4c 69  ] added for SQLi
2fa80 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a  te 3.20.0..**.**
2fa90 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2faa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2fab0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2fac0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2fad0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2fae0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2faf0 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2fb00 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2fb10 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2fb20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2fb30 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2fb40 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2fb50 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2fb60 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2fb70 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2fb80 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2fb90 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2fba0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2fbb0 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2fbc0 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2fbd0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2fbe0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2fbf0 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2fc00 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2fc10 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2fc20 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2fc30 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2fc40 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2fc50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2fc60 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2fc70 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2fc80 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2fc90 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2fca0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2fcb0 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2fcc0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2fcd0 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2fce0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2fcf0 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2fd00 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2fd10 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
2fd20 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
2fd30 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
2fd40 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
2fd50 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
2fd60 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
2fd70 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2fd80 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
2fd90 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
2fda0 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
2fdb0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2fdc0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2fdd0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2fde0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2fdf0 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2fe00 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2fe10 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2fe20 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2fe30 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2fe40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2fe50 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2fe60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2fe70 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2fe80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2fe90 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2fea0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2feb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2fec0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2fed0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2fee0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
2fef0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2ff00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2ff10 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2ff20 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2ff30 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2ff40 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2ff50 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2ff60 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2ff70 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2ff80 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ff90 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
2ffa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ffb0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49  t, double);.SQLI
2ffc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ffd0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
2ffe0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2fff0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
30000 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
30010 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
30020 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
30030 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49  te3_int64);.SQLI
30040 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30050 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
30060 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
30070 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
30080 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
30090 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
300a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
300b0 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69  ,int,void(*)(voi
300c0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
300d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
300e0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
300f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
30100 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
30110 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
30120 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
30130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
30140 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
30150 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
30160 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
30170 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
30180 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
30190 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
301a0 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
301b0 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ing);.SQLITE_API
301c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
301d0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
301e0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
301f0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
30200 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
30210 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
30220 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73  ointer(sqlite3_s
30230 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a  tmt*, int, void*
30240 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f  , const char*,vo
30250 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
30260 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
30270 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
30280 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
30290 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
302a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
302b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
302c0 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
302d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
302e0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  e3_uint64);../*.
302f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
30300 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
30310 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eters.** METHOD:
30320 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30330 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
30340 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
30350 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
30360 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
30370 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
30380 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30390 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
303a0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
303b0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
303c0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
303d0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
303e0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
303f0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
30400 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
30410 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
30420 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
30430 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
30440 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
30450 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
30460 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
30470 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
30480 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
30490 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
304a0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
304b0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
304c0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
304d0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
304e0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
304f0 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
30500 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
30510 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
30520 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
30530 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
30540 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
30550 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
30560 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
30570 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
30580 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
30590 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
305a0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
305b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
305c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
305d0 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
305e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
305f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30600 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
30610 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
30620 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
30630 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
30640 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30650 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
30660 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
30670 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
30680 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
30690 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
306a0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
306b0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
306c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
306d0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
306e0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
306f0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
30700 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
30710 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
30720 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
30730 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
30740 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
30750 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
30760 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
30770 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
30780 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
30790 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
307a0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
307b0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
307c0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
307d0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
307e0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
307f0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
30800 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
30810 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
30820 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
30830 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
30840 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
30850 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
30860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
30870 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
30880 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
30890 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
308a0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
308b0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
308c0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
308d0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
308e0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
308f0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
30900 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
30910 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
30920 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
30930 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
30940 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
30950 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
30960 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
30970 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
30980 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
30990 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
309a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f  epare16_v2()], o
309b0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
309c0 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v3()]..**.*
309d0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
309e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
309f0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
30a00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30a10 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
30a20 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
30a30 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30a40 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
30a50 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
30a60 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
30a70 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
30a80 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
30a90 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
30aa0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
30ab0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
30ac0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
30ad0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
30ae0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30af0 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
30b00 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
30b10 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
30b20 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
30b30 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
30b40 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
30b50 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
30b60 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
30b70 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
30b80 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
30b90 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
30ba0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
30bb0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
30bc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
30bd0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
30be0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
30bf0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
30c00 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
30c10 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
30c20 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
30c30 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
30c40 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
30c50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
30c60 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
30c70 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
30c80 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
30c90 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
30ca0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
30cb0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
30cc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30cd0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
30ce0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
30cf0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
30d00 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
30d10 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
30d20 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
30d30 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
30d40 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
30d50 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
30d60 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
30d70 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
30d80 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
30d90 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
30da0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30db0 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
30dc0 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
30dd0 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
30de0 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
30df0 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
30e00 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
30e10 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
30e20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30e30 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
30e40 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
30e50 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
30e60 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
30e70 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
30e80 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
30e90 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
30ea0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
30eb0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
30ec0 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
30ed0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
30ee0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
30ef0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
30f00 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
30f10 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
30f20 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
30f30 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
30f40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30f50 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74  ]. ^If this rout
30f60 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ine returns 0, t
30f70 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a  hat means the .*
30f80 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
30f90 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e  ement] returns n
30fa0 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  o data (for exam
30fb0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
30fc0 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a  ..** ^However, j
30fd0 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73  ust because this
30fe0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
30ff0 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62   a positive numb
31000 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d  er does not.** m
31010 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20  ean that one or 
31020 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74  more rows of dat
31030 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e  a will be return
31040 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73  ed.  ^A SELECT s
31050 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c  tatement.** will
31060 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70   always have a p
31070 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f  ositive sqlite3_
31080 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62  column_count() b
31090 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ut depending on 
310a0 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  the.** WHERE cla
310b0 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
310c0 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f  and the table co
310d0 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20  ntent, it might 
310e0 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a  return no rows..
310f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
31100 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
31110 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
31120 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
31130 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
31140 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
31150 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31160 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
31170 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
31180 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31190 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
311a0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
311b0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
311c0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
311d0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
311e0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
311f0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
31200 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
31210 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
31220 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
31230 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
31240 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
31250 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
31260 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
31270 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
31280 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
31290 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
312a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
312b0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
312c0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
312d0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
312e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
312f0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
31300 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
31310 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
31320 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
31330 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
31340 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
31350 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
31360 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
31370 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
31380 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
31390 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
313a0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
313b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
313c0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
313d0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
313e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
313f0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
31400 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
31410 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
31420 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
31430 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
31440 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
31450 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
31460 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
31470 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
31480 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
31490 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
314a0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
314b0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
314c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
314d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
314e0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
314f0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
31500 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
31510 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
31520 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
31530 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
31540 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
31550 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
31560 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
31570 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
31580 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
31590 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
315a0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
315b0 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
315c0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
315d0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
315e0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
315f0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
31600 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
31610 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
31620 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
31630 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
31640 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
31650 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53  o the next..*/.S
31660 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31670 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
31680 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
31690 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
316a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
316b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
316c0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
316d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
316e0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
316f0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
31700 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
31710 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
31720 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31730 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
31740 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
31750 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
31760 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
31770 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
31780 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
31790 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
317a0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
317b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
317c0 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
317d0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
317e0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
317f0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
31800 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
31810 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
31820 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
31830 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
31840 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
31850 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
31860 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
31870 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
31880 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
31890 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
318a0 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
318b0 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
318c0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
318d0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
318e0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
318f0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
31900 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31910 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
31920 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
31930 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
31940 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
31950 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
31960 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
31970 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
31980 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
31990 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
319a0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
319b0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
319c0 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
319d0 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
319e0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
319f0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
31a00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
31a10 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
31a20 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
31a30 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
31a40 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
31a50 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
31a60 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
31a70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
31a80 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
31a90 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
31aa0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
31ab0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
31ac0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
31ad0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
31ae0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
31af0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
31b00 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
31b10 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
31b20 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
31b30 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
31b40 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
31b50 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
31b60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
31b70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
31b80 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
31b90 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
31ba0 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
31bb0 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
31bc0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
31bd0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
31be0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
31bf0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
31c00 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
31c10 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
31c20 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
31c30 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
31c40 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
31c50 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
31c60 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
31c70 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
31c80 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
31c90 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
31ca0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
31cb0 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
31cc0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
31cd0 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
31ce0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
31cf0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
31d00 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
31d10 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
31d20 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
31d30 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
31d40 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
31d50 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
31d60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
31d70 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
31d80 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
31d90 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
31da0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
31db0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
31dc0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
31dd0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
31de0 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
31df0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
31e00 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
31e10 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
31e20 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
31e30 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
31e40 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
31e50 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
31e60 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
31e70 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
31e80 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
31e90 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
31ea0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
31eb0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
31ec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31ed0 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
31ee0 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
31ef0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
31f00 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
31f10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
31f20 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
31f30 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
31f40 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
31f50 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
31f60 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
31f70 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
31f80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31f90 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
31fa0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
31fb0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31fc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
31fd0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
31fe0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
31ff0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
32000 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
32010 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32020 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
32030 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
32040 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
32050 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
32060 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
32070 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32080 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
32090 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
320a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
320b0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
320c0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
320d0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
320e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
320f0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
32100 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
32110 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32120 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
32130 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
32140 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
32150 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
32160 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
32170 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
32180 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32190 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
321a0 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
321b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
321c0 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
321d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
321e0 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
321f0 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
32200 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
32210 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
32220 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
32230 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
32240 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
32250 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
32260 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
32270 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
32280 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
32290 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
322a0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
322b0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
322c0 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
322d0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
322e0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
322f0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
32300 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
32310 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
32320 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
32330 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
32340 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
32350 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
32360 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
32370 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
32380 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
32390 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
323a0 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
323b0 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
323c0 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
323d0 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
323e0 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
323f0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
32400 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
32410 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
32420 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
32430 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
32440 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
32450 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
32460 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
32470 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
32480 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
32490 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
324a0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
324b0 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
324c0 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
324d0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
324e0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
324f0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
32500 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
32510 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
32520 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
32530 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
32540 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
32550 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
32560 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
32570 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
32580 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
32590 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
325a0 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
325b0 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  values..*/.SQLIT
325c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
325d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
325e0 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
325f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
32600 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
32610 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
32620 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
32630 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
32640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32650 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
32660 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
32670 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
32680 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  _stmt.**.** Afte
32690 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
326a0 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
326b0 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
326c0 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69   any of.** [sqli
326d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
326e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
326f0 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69  are_v3()], [sqli
32700 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
32710 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
32720 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
32730 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
32740 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
32750 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
32760 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
32770 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32780 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
32790 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
327a0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
327b0 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
327c0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
327d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
327e0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
327f0 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
32800 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
32810 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
32820 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
32830 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
32840 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
32850 77 65 72 20 22 76 58 22 20 69 6e 74 65 72 66 61  wer "vX" interfa
32860 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ces.** [sqlite3_
32870 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b  prepare_v3()], [
32880 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
32890 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
328a0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c  prepare16_v3()],
328b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
328c0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
328d0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
328e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
328f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
32900 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32910 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
32920 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
32930 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65 72 66   new "vX" interf
32940 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
32950 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
32960 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
32970 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
32980 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
32990 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
329a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
329b0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
329c0 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
329d0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
329e0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
329f0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
32a00 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
32a10 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
32a20 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
32a30 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
32a40 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
32a50 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
32a60 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
32a70 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
32a80 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
32a90 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
32aa0 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
32ab0 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
32ac0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
32ad0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
32ae0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
32af0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
32b00 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
32b10 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
32b20 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
32b30 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
32b40 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
32b50 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
32b60 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
32b70 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
32b80 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
32b90 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
32ba0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
32bb0 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
32bc0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
32bd0 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
32be0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
32bf0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
32c00 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
32c10 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
32c20 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
32c30 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
32c40 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
32c50 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
32c60 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
32c70 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
32c80 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
32c90 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
32ca0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
32cb0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
32cc0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
32cd0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
32ce0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
32cf0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
32d00 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
32d10 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
32d20 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
32d30 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
32d40 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
32d50 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
32d60 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
32d70 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
32d80 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
32d90 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
32da0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
32db0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
32dc0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
32dd0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
32de0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
32df0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
32e00 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
32e10 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
32e20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
32e30 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
32e40 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
32e50 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
32e60 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
32e70 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
32e80 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
32e90 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
32ea0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
32eb0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
32ec0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
32ed0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
32ee0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
32ef0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
32f00 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
32f10 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
32f20 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
32f30 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
32f40 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
32f50 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
32f60 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
32f70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
32f80 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
32f90 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
32fa0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
32fb0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
32fc0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
32fd0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
32fe0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
32ff0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
33000 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
33010 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
33020 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
33030 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
33040 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
33050 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
33060 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
33070 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
33080 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
33090 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
330a0 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
330b0 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
330c0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
330d0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
330e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
330f0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
33100 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
33110 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
33120 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
33130 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
33140 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
33150 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
33160 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
33170 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
33180 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
33190 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
331a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
331b0 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
331c0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
331d0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
331e0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
331f0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
33200 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
33210 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
33220 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
33230 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
33240 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33250 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
33260 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
33270 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
33280 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
33290 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
332a0 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
332b0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
332c0 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
332d0 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
332e0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
332f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
33300 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
33310 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
33320 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
33330 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
33340 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
33350 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
33360 75 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f  ut after [versio
33370 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61  n 3.6.23.1] ([da
33380 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a  teof:3.6.23.1],.
33390 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
333a0 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
333b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
333c0 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
333d0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
333e0 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
333f0 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
33400 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
33410 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
33420 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
33430 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
33440 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
33450 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
33460 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
33470 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
33480 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
33490 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
334a0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
334b0 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
334c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
334d0 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
334e0 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
334f0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
33500 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
33510 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
33520 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
33530 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
33540 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
33550 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
33560 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
33570 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
33580 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
33590 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
335a0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
335b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
335c0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
335d0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
335e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
335f0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
33600 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
33610 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
33620 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
33630 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
33640 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
33650 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
33660 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
33670 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
33680 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
33690 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
336a0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
336b0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
336c0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
336d0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
336e0 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
336f0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
33700 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
33710 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
33720 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72  pare_v2()].** or
33730 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33740 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  e16_v2()] or [sq
33750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
33760 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v3()] instead.**
33770 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
33780 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
33790 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
337a0 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
337b0 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
337c0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
337d0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
337e0 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
337f0 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
33800 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
33810 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 58  e use of the "vX
33820 22 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  " interfaces is 
33830 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
33840 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
33850 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
33860 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
33870 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
33880 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
33890 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
338a0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
338b0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
338c0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
338d0 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
338e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
338f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
33900 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
33910 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
33920 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
33930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33940 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
33950 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
33960 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
33970 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
33980 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
33990 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
339a0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
339b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
339c0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
339d0 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
339e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
339f0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
33a00 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
33a10 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
33a20 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
33a30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
33a40 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
33a50 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
33a60 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
33a70 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
33a80 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
33a90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
33aa0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
33ab0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
33ac0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
33ad0 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
33ae0 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
33af0 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
33b00 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
33b10 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
33b20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
33b30 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
33b40 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
33b50 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
33b60 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
33b70 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
33b80 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
33b90 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
33ba0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
33bb0 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
33bc0 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
33bd0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
33be0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33bf0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
33c00 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
33c10 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
33c20 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
33c30 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
33c40 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
33c50 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
33c60 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
33c70 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
33c80 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
33c90 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
33ca0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
33cb0 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
33cc0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
33cd0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
33ce0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
33cf0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
33d00 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
33d10 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
33d20 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
33d30 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
33d40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
33d50 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
33d60 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
33d70 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
33d80 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
33d90 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
33da0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
33db0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
33dc0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
33dd0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
33de0 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
33df0 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
33e00 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
33e10 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
33e20 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
33e30 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
33e40 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
33e50 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
33e60 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
33e70 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
33e80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
33e90 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
33ea0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
33eb0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
33ec0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
33ed0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
33ee0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
33ef0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
33f00 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
33f10 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
33f20 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
33f30 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
33f40 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
33f50 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
33f60 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
33f70 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
33f80 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
33f90 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
33fa0 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d  mt.**.** <b>Summ
33fb0 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f  ary:</b>.** <blo
33fc0 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62  ckquote><table b
33fd0 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64  order=0 cellpadd
33fe0 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e  ing=0 cellspacin
33ff0 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  g=0>.** <tr><td>
34000 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
34010 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72  n_blob</b><td>&r
34020 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73  arr;<td>BLOB res
34030 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
34040 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
34050 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26  _double</b><td>&
34060 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65  rarr;<td>REAL re
34070 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
34080 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
34090 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61  n_int</b><td>&ra
340a0 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e  rr;<td>32-bit IN
340b0 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20  TEGER result.** 
340c0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
340d0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c  e3_column_int64<
340e0 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
340f0 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20  >64-bit INTEGER 
34100 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
34110 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
34120 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e  umn_text</b><td>
34130 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20  &rarr;<td>UTF-8 
34140 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  TEXT result.** <
34150 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
34160 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c  3_column_text16<
34170 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
34180 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72 65 73  >UTF-16 TEXT res
34190 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
341a0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
341b0 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72  _value</b><td>&r
341c0 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75  arr;<td>The resu
341d0 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71  lt as an .** [sq
341e0 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72  lite3_value|unpr
341f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
34200 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  value] object..*
34210 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b  * <tr><td>&nbsp;
34220 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e  <td>&nbsp;<td>&n
34230 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  bsp;.** <tr><td>
34240 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
34250 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26  n_bytes</b><td>&
34260 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  rarr;<td>Size of
34270 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20   a BLOB.** or a 
34280 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c  UTF-8 TEXT resul
34290 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74  t in bytes.** <t
342a0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
342b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26  _column_bytes16&
342c0 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a  nbsp;&nbsp;</b>.
342d0 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62  ** <td>&rarr;&nb
342e0 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a  sp;&nbsp;<td>Siz
342f0 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54  e of UTF-16.** T
34300 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20  EXT in bytes.** 
34310 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
34320 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f  e3_column_type</
34330 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
34340 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74  Default.** datat
34350 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ype of the resul
34360 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62  t.** </table></b
34370 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
34380 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e   <b>Details:</b>
34390 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
343a0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
343b0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
343c0 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
343d0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
343e0 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
343f0 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
34400 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
34410 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
34420 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
34430 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
34440 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
34450 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
34460 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
34470 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
34480 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
34490 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
344a0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
344b0 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
344c0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
344d0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
344e0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
344f0 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
34500 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
34510 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
34520 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
34530 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
34540 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
34550 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
34560 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
34570 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
34580 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
34590 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
345a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
345b0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
345c0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
345d0 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
345e0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
345f0 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
34600 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
34610 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
34620 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
34630 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
34640 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
34650 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
34660 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
34670 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
34680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
34690 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
346a0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
346b0 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
346c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
346d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
346e0 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
346f0 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
34700 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
34710 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
34720 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
34730 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
34740 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
34750 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
34760 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
34770 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
34780 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
34790 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
347a0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
347b0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
347c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
347d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
347e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
347f0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
34800 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
34810 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
34820 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
34830 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
34840 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
34850 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
34860 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
34870 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
34880 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73  *.** The first s
34890 69 78 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f  ix interfaces (_
348a0 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f  blob, _double, _
348b0 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65  int, _int64, _te
348c0 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29  xt, and _text16)
348d0 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20  .** each return 
348e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72  the value of a r
348f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20  esult column in 
34900 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 20  a specific data 
34910 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74  format.  If.** t
34920 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
34930 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c   is not initiall
34940 79 20 69 6e 20 74 68 65 20 72 65 71 75 65 73 74  y in the request
34950 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65  ed format (for e
34960 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68  xample,.** if th
34970 65 20 71 75 65 72 79 20 72 65 74 75 72 6e 73 20  e query returns 
34980 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74 20 74  an integer but t
34990 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
349a0 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72 66 61  n_text() interfa
349b0 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f  ce.** is used to
349c0 20 65 78 74 72 61 63 74 20 74 68 65 20 76 61 6c   extract the val
349d0 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f  ue) then an auto
349e0 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65  matic type conve
349f0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
34a00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
34a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
34a20 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
34a30 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
34a40 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
34a50 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
34a60 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
34a70 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
34a80 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
34a90 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
34aa0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
34ab0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
34ac0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
34ad0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
34ae0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
34af0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
34b00 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  L]..** The retur
34b10 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74  n value of sqlit
34b20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
34b30 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
34b40 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20  decide which.** 
34b50 6f 66 20 74 68 65 20 66 69 72 73 74 20 73 69 78  of the first six
34b60 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c   interface shoul
34b70 64 20 62 65 20 75 73 65 64 20 74 6f 20 65 78 74  d be used to ext
34b80 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20  ract the column 
34b90 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61  value..** The va
34ba0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
34bb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34bc0 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
34bd0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a  aningful if no.*
34be0 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65  * automatic type
34bf0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
34c00 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74  e occurred for t
34c10 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73  he value in ques
34c20 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72  tion.  .** After
34c30 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
34c40 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f  on, the result o
34c50 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  f calling sqlite
34c60 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
34c70 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c  ** is undefined,
34c80 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73   though harmless
34c90 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
34ca0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
34cb0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
34cc0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
34cd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
34ce0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
34cf0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
34d00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  .**.** If the re
34d10 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
34d20 72 20 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c  r a TEXT string,
34d30 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
34d40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
34d50 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  .** or sqlite3_c
34d60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
34d70 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e 20 62  interfaces can b
34d80 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d  e used to determ
34d90 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20  ine the size.** 
34da0 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  of that BLOB or 
34db0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^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 38 20  a BLOB or UTF-8 
34de0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
34df0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34e00 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
34e10 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
34e20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
34e30 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
34e40 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
34e50 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
34e60 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
34e70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34e80 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
34e90 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
34ea0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
34eb0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
34ec0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
34ed0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
34ee0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
34ef0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
34f00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
34f10 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
34f20 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
34f30 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
34f40 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
34f50 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
34f60 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
34f70 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
34f80 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
34f90 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
34fa0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
34fb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
34fc0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
34fd0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
34fe0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
34ff0 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
35000 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
35010 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
35020 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
35030 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
35040 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
35050 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
35060 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
35070 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
35080 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
35090 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
350a0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
350b0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
350c0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
350d0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
350e0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
350f0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
35100 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
35110 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35120 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
35130 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
35140 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
35150 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
35160 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
35170 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
35180 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
35190 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
351a0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
351b0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
351c0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
351d0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
351e0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
351f0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
35200 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
35210 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
35220 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
35230 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35240 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
35250 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
35260 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
35270 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
35280 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
35290 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
352a0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
352b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
352c0 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
352d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
352e0 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
352f0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
35300 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
35310 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
35320 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
35330 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
35340 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
35350 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
35360 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
35370 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
35380 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
35390 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
353a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
353b0 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
353c0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
353d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
353e0 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
353f0 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
35400 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
35410 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20  <b>Warning:</b> 
35420 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
35430 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
35440 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
35450 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
35460 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
35470 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49  alue] object.  I
35480 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65  n a multithreade
35490 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a  d environment,.*
354a0 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  * an unprotected
354b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
354c0 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62  bject may only b
354d0 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69  e used safely wi
354e0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  th.** [sqlite3_b
354f0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
35500 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35510 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
35520 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
35530 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
35540 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
35550 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
35560 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
35570 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
35580 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
35590 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
355a0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
355b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
355c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
355d0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
355e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
355f0 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20  e_bytes()], the 
35600 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20  behavior is not 
35610 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48  threadsafe..** H
35620 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  ence, the sqlite
35630 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
35640 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
35650 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75   normally only u
35660 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65  seful within the
35670 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35680 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74  of .** [applicat
35690 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
356a0 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76  functions] or [v
356b0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20  irtual tables], 
356c0 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f  not within.** to
356d0 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74  p-level applicat
356e0 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  ion code..**.** 
356f0 54 68 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  The these routin
35700 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74  es may attempt t
35710 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61  o convert the da
35720 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65  tatype of the re
35730 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78  sult..** ^For ex
35740 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
35750 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
35760 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
35770 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
35780 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
35790 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
357a0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
357b0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
357c0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
357d0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
357e0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
357f0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
35800 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
35810 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
35820 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
35830 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
35840 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
35850 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
35860 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
35870 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
35880 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
35890 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
358a0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
358b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
358c0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
358d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
358e0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
358f0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
35900 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
35910 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
35920 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
35930 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
35940 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
35950 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
35960 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
35970 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
35980 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
35990 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
359a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
359b0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
359c0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
359d0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
359e0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
359f0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
35a00 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
35a10 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
35a20 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
35a30 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
35a40 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
35a50 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
35a60 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
35a70 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
35a80 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
35a90 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
35aa0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
35ab0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
35ac0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
35ad0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
35ae0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
35af0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
35b00 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
35b10 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
35b20 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
35b30 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
35b40 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
35b50 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
35b60 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
35b70 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
35b80 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
35b90 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
35ba0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
35bb0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
35bc0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
35bd0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
35be0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
35bf0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
35c00 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
35c10 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
35c20 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
35c30 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
35c40 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
35c50 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
35c60 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
35c70 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
35c80 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
35c90 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
35ca0 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
35cb0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
35cc0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
35cd0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
35ce0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
35cf0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
35d00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35d10 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
35d20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35d30 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
35d40 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
35d50 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
35d60 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
35d70 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
35d80 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
35d90 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
35da0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
35db0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
35dc0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
35dd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
35de0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
35df0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
35e00 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
35e10 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
35e20 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
35e30 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
35e40 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
35e50 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
35e60 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
35e70 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
35e80 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
35e90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35ea0 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
35eb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35ec0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
35ed0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
35ee0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
35ef0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
35f00 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
35f10 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
35f20 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
35f30 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
35f40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35f50 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
35f60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
35f70 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
35f80 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
35f90 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
35fa0 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
35fb0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
35fc0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
35fd0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
35fe0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
35ff0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
36000 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
36010 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
36020 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
36030 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
36040 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
36050 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
36060 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
36070 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
36080 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
36090 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
360a0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
360b0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
360c0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
360d0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
360e0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
360f0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
36100 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
36110 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
36120 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
36130 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
36140 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20  e safest policy 
36150 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
36160 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
36170 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
36180 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
36190 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
361a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
361b0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
361c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
361d0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
361e0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
361f0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
36200 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
36210 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
36220 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
36230 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
36240 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
36250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36260 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
36270 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
36280 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
36290 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
362a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
362b0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
362c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
362d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
362e0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
362f0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
36300 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
36310 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
36320 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
36330 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36340 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
36350 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
36360 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
36370 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
36380 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
36390 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
363a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
363b0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
363c0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
363d0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
363e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
363f0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
36400 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
36410 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
36420 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
36430 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
36440 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
36450 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
36460 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
36470 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
36480 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
36490 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
364a0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
364b0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
364c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
364d0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
364e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
364f0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
36500 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
36510 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
36520 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
36530 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
36540 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e  matically.  Do n
36550 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  ot pass the poin
36560 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
36570 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
36580 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
36590 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
365a0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
365b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
365c0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
365d0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
365e0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
365f0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
36600 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
36610 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
36620 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
36630 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
36640 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
36650 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
36660 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
36670 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
36680 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
36690 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
366a0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
366b0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
366c0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
366d0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
366e0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
366f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
36700 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
36710 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
36720 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36730 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
36740 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  API double sqlit
36750 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
36760 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36770 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
36780 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
36790 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
367a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
367b0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
367c0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
367d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
367e0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
367f0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
36800 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
36810 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
36820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36830 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
36840 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
36850 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
36860 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
36870 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
36880 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36890 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
368a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
368b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
368c0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
368d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
368e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
368f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36900 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36910 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
36920 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
36930 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
36940 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36950 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
36960 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
36970 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
36980 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36990 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
369a0 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
369b0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
369c0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
369d0 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
369e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
369f0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
36a00 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
36a10 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
36a20 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
36a30 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
36a40 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
36a50 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
36a60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
36a70 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
36a80 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
36a90 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
36aa0 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
36ab0 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
36ac0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
36ad0 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
36ae0 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
36af0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
36b00 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
36b10 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
36b20 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
36b30 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
36b40 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
36b50 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
36b60 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
36b70 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
36b80 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
36b90 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
36ba0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
36bb0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
36bc0 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
36bd0 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
36be0 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
36bf0 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
36c00 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
36c10 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
36c20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
36c30 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
36c40 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
36c50 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
36c60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
36c70 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
36c80 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
36c90 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
36ca0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
36cb0 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
36cc0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
36cd0 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
36ce0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
36cf0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
36d00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
36d10 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
36d20 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
36d30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36d40 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
36d50 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
36d60 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
36d70 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
36d80 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
36d90 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
36da0 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
36db0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
36dc0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
36dd0 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
36de0 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
36df0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
36e00 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
36e10 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
36e20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
36e30 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
36e40 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
36e50 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
36e60 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
36e70 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
36e80 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
36e90 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
36ea0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
36eb0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
36ec0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
36ed0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d  ment Object.** M
36ee0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
36ef0 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  tmt.**.** The sq
36f00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
36f10 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
36f20 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
36f30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36f40 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
36f50 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
36f60 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
36f70 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
36f80 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
36f90 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
36fa0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
36fb0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
36fc0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
36fd0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
36fe0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
36ff0 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
37000 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
37010 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
37020 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
37030 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
37040 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
37050 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
37060 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
37070 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
37080 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
37090 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
370a0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
370b0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
370c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
370d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
370e0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
370f0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
37100 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
37110 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
37120 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
37130 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
37140 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
37150 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
37160 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
37170 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
37180 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
37190 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
371a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
371b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
371c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
371d0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
371e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
371f0 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
37200 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
37210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
37220 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
37230 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
37240 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
37250 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
37260 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
37270 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
37280 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
37290 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
372a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
372b0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
372c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
372d0 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ] S..*/.SQLITE_A
372e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  PI int sqlite3_r
372f0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
37300 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
37310 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
37320 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
37330 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
37340 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
37350 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
37360 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
37370 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
37380 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
37390 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
373a0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
373b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
373c0 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
373d0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
373e0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
373f0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
37400 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
37410 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
37420 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
37430 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
37440 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
37450 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
37460 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
37470 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
37480 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
37490 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
374a0 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
374b0 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
374c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
374d0 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
374e0 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
374f0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
37500 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
37510 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
37520 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
37530 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
37540 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
37550 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
37560 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
37570 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37580 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
37590 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
375a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
375b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
375c0 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
375d0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
375e0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
375f0 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
37600 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
37610 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
37620 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
37630 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
37640 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
37650 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
37660 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
37670 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
37680 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
37690 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
376a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
376b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
376c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
376d0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
376e0 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
376f0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
37700 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
37710 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
37720 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
37730 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
37740 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
37750 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
37760 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
37770 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
37780 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
37790 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
377a0 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
377b0 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
377c0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
377d0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
377e0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
377f0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
37800 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
37810 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
37820 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
37830 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
37840 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
37850 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
37860 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
37870 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
37880 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
37890 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
378a0 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
378b0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
378c0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
378d0 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
378e0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
378f0 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
37900 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
37910 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
37920 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
37930 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
37940 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
37950 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
37960 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
37970 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
37980 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
37990 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
379a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
379b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
379c0 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
379d0 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
379e0 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
379f0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
37a00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
37a10 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
37a20 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20  arameters.  The 
37a30 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
37a40 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61  ld set this para
37a50 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c  meter to.** [SQL
37a60 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20  ITE_UTF16LE] if 
37a70 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
37a80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
37a90 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  kes .** [sqlite3
37aa0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
37ab0 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20  )] on an input, 
37ac0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
37ad0 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d  BE] if the.** im
37ae0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
37af0 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61  okes [sqlite3_va
37b00 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20  lue_text16be()] 
37b10 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a  on an input, or.
37b20 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
37b30 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  ] if [sqlite3_va
37b40 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73  lue_text16()] is
37b50 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54   used, or [SQLIT
37b60 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72  E_UTF8].** other
37b70 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65  wise.  ^The same
37b80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61   SQL function ma
37b90 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
37ba0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
37bb0 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e  sing.** differen
37bc0 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  t preferred text
37bd0 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68   encodings, with
37be0 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65   different imple
37bf0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a  mentations for.*
37c00 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e  * each encoding.
37c10 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
37c20 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
37c30 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
37c40 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
37c50 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
37c60 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
37c70 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
37c80 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
37c90 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
37ca0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sion..**.** ^The
37cb0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
37cc0 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79  r may optionally
37cd0 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53   be ORed with [S
37ce0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
37cf0 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  TIC].** to signa
37d00 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74  l that the funct
37d10 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ion will always 
37d20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
37d30 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20  result given.** 
37d40 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20  the same inputs 
37d50 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20  within a single 
37d60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
37d70 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  Most SQL functio
37d80 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d  ns are.** determ
37d90 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75  inistic.  The bu
37da0 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29  ilt-in [random()
37db0 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  ] SQL function i
37dc0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
37dd0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  a.** function th
37de0 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d  at is not determ
37df0 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51  inistic.  The SQ
37e00 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e  Lite query plann
37e10 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a  er is able to.**
37e20 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f   perform additio
37e30 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  nal optimization
37e40 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74  s on determinist
37e50 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f  ic functions, so
37e60 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b   use.** of the [
37e70 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
37e80 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65  STIC] flag is re
37e90 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20  commended where 
37ea0 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  possible..**.** 
37eb0 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
37ec0 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
37ed0 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
37ee0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
37ef0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
37f00 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
37f10 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
37f20 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
37f30 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
37f40 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ].)^.**.** ^The 
37f50 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61  sixth, seventh a
37f60 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65  nd eighth parame
37f70 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
37f80 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
37f90 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
37fa0 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
37fb0 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
37fc0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
37fd0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
37fe0 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
37ff0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
38000 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
38010 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
38020 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
38030 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
38040 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70  inters must be p
38050 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
38060 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
38070 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
38080 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
38090 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
380a0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
380b0 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
380c0 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
380d0 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20  LL pointer must 
380e0 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
380f0 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
38100 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
38110 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
38120 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
38130 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72  ULL pointers for
38140 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
38150 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73  ion.** callbacks
38160 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65  ..**.** ^(If the
38170 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
38180 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
38190 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
381a0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
381b0 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74   then it is dest
381c0 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61  ructor for the a
381d0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
381e0 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65  pointer. .** The
381f0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69   destructor is i
38200 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
38210 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
38220 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62  ted, either by b
38230 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64  eing.** overload
38240 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64  ed or when the d
38250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38260 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20  on closes.)^.** 
38270 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
38280 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20  is also invoked 
38290 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  if the call to.*
382a0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
382b0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66  _function_v2() f
382c0 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74  ails..** ^When t
382d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61  he destructor ca
382e0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65  llback of the te
382f0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  nth parameter is
38300 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20   invoked, it.** 
38310 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67  is passed a sing
38320 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
38330 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  h is a copy of t
38340 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
38350 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ata .** pointer 
38360 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69  which was the fi
38370 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  fth parameter to
38380 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38390 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  function_v2()..*
383a0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
383b0 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
383c0 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
383d0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
383e0 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
383f0 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
38400 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
38410 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
38420 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
38430 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
38440 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
38450 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
38460 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
38470 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
38480 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
38490 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
384a0 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
384b0 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
384c0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
384d0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
384e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
384f0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
38500 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
38510 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
38520 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
38530 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
38540 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
38550 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
38560 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
38570 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
38580 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
38590 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
385a0 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
385b0 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
385c0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
385d0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
385e0 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
385f0 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
38600 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
38610 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
38620 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
38630 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
38640 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
38650 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
38660 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
38670 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
38680 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
38690 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
386a0 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
386b0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
386c0 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
386d0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
386e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
386f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70  s..**.** ^An app
38700