System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact ebaf978474f92ac761cf31967b7793e277cffe8e:


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 0a 2a 2a 0a  source tree..**.
10c0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
10d0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
10e0: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
10f0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1100: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
1110: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
1120: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
1130: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
1140: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1160: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1170: 2e 32 30 2e 30 22 0a 23 64 65 66 69 6e 65 20 53  .20.0".#define S
1180: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1190: 4d 42 45 52 20 33 30 32 30 30 30 30 0a 23 64 65  MBER 3020000.#de
11a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
11b0: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 37  CE_ID      "2017
11c0: 2d 30 37 2d 32 35 20 31 35 3a 31 32 3a 30 31 20  -07-25 15:12:01 
11d0: 66 33 39 63 62 37 36 62 33 33 34 37 62 61 62 61  f39cb76b3347baba
11e0: 32 32 66 32 63 33 32 39 65 37 34 30 33 36 37 31  22f2c329e7403671
11f0: 30 62 36 34 36 32 30 34 31 34 34 33 33 61 39 35  0b64620414433a95
1200: 32 64 65 38 64 34 34 64 61 37 39 62 61 38 64 39  2de8d44da79ba8d9
1210: 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  "../*.** CAPI3RE
1220: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1230: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
1240: 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ers.** KEYWORDS:
1250: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1260: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
1270: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
1280: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65  terfaces provide
1290: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
12a0: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
12b0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a  LITE_VERSION],.*
12c0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
12d0: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b  N_NUMBER], and [
12e0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
12f0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1300: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61   macros.** but a
1310: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
1320: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
1330: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
1340: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61  ader file.  ^(Ca
1350: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61  utious.** progra
1360: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c  mmers might incl
1370: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ude assert() sta
1380: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72  tements in their
1390: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
13a0: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76  ** verify that v
13b0: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
13c0: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  y these interfac
13d0: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63  es match the mac
13e0: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65  ros in.** the he
13f0: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65  ader, and thus e
1400: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
1410: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a  pplication is.**
1420: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1430: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20  atching library 
1440: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73  and header files
1450: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
1460: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73  ote><pre>.** ass
1470: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62  ert( sqlite3_lib
1480: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1490: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ==SQLITE_VERSION
14a0: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73  _NUMBER );.** as
14b0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
14c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c  ite3_sourceid(),
14d0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
14e0: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
14f0: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1500: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1510: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1520: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1530: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1540: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1550: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1560: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
1570: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
1580: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
1590: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
15a0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
15b0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
15c0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
15d0: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
15e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
15f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1600: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1610: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1620: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1630: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
1640: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1650: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1660: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
1670: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
1680: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
1690: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
16a0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
16b0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
16c0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
16d0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
16e0: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
16f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1700: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
1710: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
1720: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1730: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1740: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61   a string consta
1750: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69  nt whose value i
1760: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68  s the same as th
1770: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  e .** [SQLITE_SO
1780: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1790: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a  ocessor macro..*
17a0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
17b0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
17c0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
17d0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
17e0: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
17f0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1800: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1810: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1820: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
1830: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1840: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
1850: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
1860: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
1870: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1880: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62   int sqlite3_lib
1890: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
18a0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
18b0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
18c0: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
18d0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
18e0: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
18f0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
1900: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
1910: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1920: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
1930: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
1940: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
1950: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
1960: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
1970: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
1980: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
1990: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
19a0: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
19b0: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
19c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19d0: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
19e0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
19f0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1a00: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
1a10: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
1a20: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
1a30: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
1a40: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
1a50: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
1a60: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
1a70: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
1a80: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
1a90: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
1aa0: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
1ab0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1ac0: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
1ad0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1ae0: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
1af0: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
1b00: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
1b10: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1b20: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1b30: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
1b40: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
1b50: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
1b60: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
1b70: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1b80: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
1b90: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ba0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
1bb0: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
1bc0: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
1bd0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
1be0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1bf0: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
1c00: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
1c10: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
1c20: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
1c30: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1c40: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1c50: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
1c60: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
1c70: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
1c80: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
1c90: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
1ca0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1cb0: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
1cc0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1cd0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1ce0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1cf0: 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45  OptName);.SQLITE
1d00: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
1d10: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1d20: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1d30: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1d40: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1d50: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1d60: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1d70: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1d80: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1d90: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1da0: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1db0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1dc0: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1dd0: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1de0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1df0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1e00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1e10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1e20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1e30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1e40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1e50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1e60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1e70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1e80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1e90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ea0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1eb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1ec0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1ed0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ee0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1ef0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1f00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1f10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1f20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1f30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1f40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1f50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1f60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1f70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1f80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1f90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1fa0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1fb0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1fc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1fd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1fe0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1ff0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
2000: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
2010: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
2020: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
2030: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
2040: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
2050: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
2060: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
2070: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
2080: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2090: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
20a0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
20b0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
20c0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
20d0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
20e0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
20f0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2100: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2110: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
2120: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
2130: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
2160: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
2170: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
2180: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
2190: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
21a0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
21b0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
21c0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
21d0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
21e0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
21f0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2200: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2210: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2220: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2230: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2240: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2250: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2260: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2270: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2280: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2290: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
22a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
22b0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
22c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
22d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
22e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
22f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2300: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2310: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2320: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2330: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2340: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2350: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2360: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2370: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2380: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2390: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
23a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
23b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
23c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
23d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
23e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
23f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2400: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2410: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2420: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2430: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2440: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2450: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2460: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2470: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2480: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2490: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
24a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
24b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24c0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
24d0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
24e0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
24f0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2500: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2510: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2520: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2530: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2540: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2550: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2560: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2570: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2580: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2590: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
25a0: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
25b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
25c0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
25d0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
25e0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
25f0: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2600: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2610: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
2620: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
2630: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
2640: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
2650: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
2660: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2670: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2680: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2690: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
26a0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
26b0: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
26c0: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
26d0: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
26e0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
26f0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2700: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2710: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
2720: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
2730: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
2740: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2750: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
2760: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
2770: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2780: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2790: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
27a0: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
27b0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
27c0: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
27d0: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
27e0: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
27f0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2800: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2810: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
2820: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
2830: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
2840: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
2850: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2860: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
2870: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2880: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2890: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
28a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
28b0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
28c0: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
28d0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
28e0: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
28f0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2900: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2910: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
2920: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
2930: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
2940: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2950: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
2960: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
2970: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2980: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2990: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
29a0: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
29b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
29c0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
29d0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
29e0: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
29f0: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2a00: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2a10: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
2a20: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2a30: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
2a40: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2a50: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2a60: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
2a70: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2a80: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2a90: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2aa0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2ab0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2ac0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2ad0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2ae0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2af0: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2b00: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2b10: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2b20: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2b30: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2b40: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2b50: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2b60: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2b70: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2b80: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2b90: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2ba0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2bb0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2bc0: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2bd0: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2be0: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2bf0: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2c00: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2c10: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2c20: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2c30: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2c40: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2c50: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2c60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2c70: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2c80: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2c90: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2ca0: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2cb0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2cc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2cd0: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2ce0: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2cf0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2d00: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2d10: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2d20: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2d30: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2d40: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2d50: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2d60: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2d70: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2d80: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2d90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2da0: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2db0: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2dc0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2dd0: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2de0: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2df0: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2e00: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2e10: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2e20: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2e30: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2e40: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2e50: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2e60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2e70: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2e80: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2e90: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2ea0: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2eb0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2ec0: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2ed0: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
2ee0: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2ef0: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
2f00: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2f10: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
2f20: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
2f30: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
2f40: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2f50: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
2f60: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
2f70: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2f80: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2f90: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
2fa0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
2fb0: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
2fc0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
2fd0: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2fe0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
2ff0: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
3000: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
3010: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
3020: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
3030: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
3040: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
3050: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
3060: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
3070: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
3080: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
3090: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
30a0: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
30b0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
30c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
30d0: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
30e0: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
30f0: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3100: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3110: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
3120: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3130: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
3140: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
3150: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
3160: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
3170: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
3180: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
3190: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
31a0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
31b0: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
31c0: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
31d0: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
31e0: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
31f0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3200: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3210: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
3220: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3230: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
3240: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
3250: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
3260: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
3270: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
3280: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
3290: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
32a0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
32b0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
32c0: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
32d0: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
32e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
32f0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3300: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3310: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
3320: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
3330: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
3340: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
3350: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
3360: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
3370: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
3380: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
3390: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
33a0: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
33b0: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
33c0: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
33d0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
33e0: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
33f0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3400: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3410: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
3420: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
3430: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
3440: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
3450: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
3460: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
3470: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
3480: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
3490: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
34a0: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
34b0: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
34c0: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
34d0: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
34e0: 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
34f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
3500: 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a  e_v2(sqlite3*);.
3510: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
3520: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
3530: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
3540: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
3550: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
3560: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
3570: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
3580: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
3590: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
35a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
35b0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
35c0: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
35d0: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
35e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35f0: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
3600: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
3610: 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ace.** METHOD: s
3620: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
3630: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3640: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
3650: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
3660: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
3670: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
3680: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
3690: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
36a0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
36b0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
36c0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
36d0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
36e0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
36f0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3700: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3710: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3720: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3730: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3740: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3750: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
3760: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
3770: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
3780: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3790: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
37a0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
37b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
37c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37d0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
37e0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
37f0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3800: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3810: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3820: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3830: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3840: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3850: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
3860: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
3870: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
3880: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
3890: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
38a0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
38b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
38c0: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
38d0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
38e0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
38f0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3900: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3910: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3920: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3930: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3940: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3950: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3960: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3970: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3980: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3990: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
39a0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
39b0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
39c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
39e0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
39f0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3a00: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3a10: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3a20: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3a30: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3a40: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3a50: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3a60: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3a70: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3a80: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3a90: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3aa0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3ab0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3ac0: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3ad0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3ae0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3af0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3b00: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3b10: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3b20: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3b30: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3b40: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3b50: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3b60: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3b70: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69  meter of.** sqli
3b80: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72  te3_exec() after
3b90: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
3ba0: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20  ge string is no 
3bb0: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a  longer needed..*
3bc0: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61  * ^If the 5th pa
3bd0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3be0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
3bf0: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72   NULL and no err
3c00: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68  ors.** occur, th
3c10: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  en sqlite3_exec(
3c20: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74  ) sets the point
3c30: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61  er in its 5th pa
3c40: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55  rameter to.** NU
3c50: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  LL before return
3c60: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  ing..**.** ^If a
3c70: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3c80: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
3c90: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
3ca0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3cb0: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
3cc0: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77  s SQLITE_ABORT w
3cd0: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20  ithout invoking 
3ce0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61  the callback aga
3cf0: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75  in and.** withou
3d00: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75  t running any su
3d10: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
3d20: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
3d30: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  The 2nd argument
3d40: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3d50: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3d60: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a  function is the.
3d70: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  ** number of col
3d80: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
3d90: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72  lt.  ^The 3rd ar
3da0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
3db0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3dc0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3dd0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3de0: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61   to strings obta
3df0: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a  ined as if from.
3e00: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
3e10: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20  mn_text()], one 
3e20: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e  for each column.
3e30: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74    ^If an element
3e40: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20   of a.** result 
3e50: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  row is NULL then
3e60: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
3e70: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ng string pointe
3e80: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c  r for the.** sql
3e90: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ea0: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70  back is a NULL p
3eb0: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74  ointer.  ^The 4t
3ec0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
3ed0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
3ee0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
3ef0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3f00: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3f10: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e  where each.** en
3f20: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74  try represents t
3f30: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65  he name of corre
3f40: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20  sponding result 
3f50: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e  column as obtain
3f60: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3f70: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
3f80: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  )]..**.** ^If th
3f90: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3fa0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3fb0: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
3fc0: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a  ter, a pointer.*
3fd0: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  * to an empty st
3fe0: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74  ring, or a point
3ff0: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  er that contains
4000: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
4010: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20   and/or .** SQL 
4020: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
4030: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
4040: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
4050: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  nd the database.
4060: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
4070: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63  d..**.** Restric
4080: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tions:.**.** <ul
4090: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  >.** <li> The ap
40a0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65  plication must e
40b0: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31  nsure that the 1
40c0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
40d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
40e0: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69  *      is a vali
40f0: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61  d and open [data
4100: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
4110: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
4120: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
4130: 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61  ot close the [da
4140: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4150: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  n] specified by.
4160: 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20  **      the 1st 
4170: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
4180: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
4190: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
41a0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
41b0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
41c0: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f  tion must not mo
41d0: 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61  dify the SQL sta
41e0: 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73  tement text pass
41f0: 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20  ed into.**      
4200: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
4210: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  r of sqlite3_exe
4220: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
4230: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
4240: 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ing..** </ul>.*/
4250: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
4260: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
4270: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
4280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4290: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
42a0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
42b0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
42c0: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
42d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
42e0: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
42f0: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28  uated */.  int (
4300: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  *callback)(void*
4310: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
4320: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63  **),  /* Callbac
4330: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  k function */.  
4340: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
4350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4360: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73             /* 1s
4370: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  t argument to ca
4380: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72  llback */.  char
4390: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
43a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43b0: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
43c0: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
43d0: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
43e0: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43  PI3REF: Result C
43f0: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4400: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64  : {result code d
4410: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
4420: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
4430: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
4440: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
4450: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
4460: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
4470: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
4480: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
4490: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
44a0: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
44b0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
44c0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
44d0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
44e0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65   See also: [exte
44f0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4500: 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f   definitions].*/
4510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4520: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
4530: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
4540: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
4550: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
4560: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
4570: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
4580: 20 20 20 20 31 20 20 20 2f 2a 20 47 65 6e 65 72      1   /* Gener
4590: 69 63 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ic error */.#def
45a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
45b0: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
45c0: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
45d0: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
45e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
45f0: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
4600: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
4610: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
4620: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
4630: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
4640: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
4650: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
4660: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
4670: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
4680: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
4690: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
46a0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
46b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
46c0: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
46d0: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
46e0: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
4710: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
4720: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
4730: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
4740: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
4750: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
4760: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
4770: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4780: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
4790: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
47a0: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
47b0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
47c0: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
47d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
47e0: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
47f0: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
4800: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
4810: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4820: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
4830: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4840: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
4850: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
4860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4870: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
4880: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
4890: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
48a0: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
48b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
48c0: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
48d0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
48e0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
48f0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
4900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
4910: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
4920: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
4930: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
4940: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4950: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
4960: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
4970: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
4980: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4990: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
49a0: 20 20 31 36 20 20 20 2f 2a 20 4e 6f 74 20 75 73    16   /* Not us
49b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
49c0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
49d0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
49e0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
49f0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4a00: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4a10: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4a20: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4a30: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4a40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4a50: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4a60: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4a70: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4a80: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4a90: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4aa0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4ab0: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ad0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4ae0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4af0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b10: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4b20: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4b30: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4b40: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4b60: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4b70: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4b80: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4b90: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4ba0: 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20 75     24   /* Not u
4bb0: 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
4bc0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
4bd0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
4be0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
4bf0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
4c00: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
4c10: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
4c20: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
4c30: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
4c40: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
4c50: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
4c60: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20  LITE_NOTICE     
4c70: 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63   27   /* Notific
4c80: 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69  ations from sqli
4c90: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65  te3_log() */.#de
4ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
4cb0: 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20  ING     28   /* 
4cc0: 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71  Warnings from sq
4cd0: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4ce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
4cf0: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
4d00: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4d10: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
4d20: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
4d30: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
4d40: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
4d50: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4d60: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
4d70: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
4d80: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
4d90: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4da0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
4db0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4dc0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
4dd0: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4de0: 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  ions}.**.** In i
4df0: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4e00: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
4e10: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
4e20: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69  turn one of 30 i
4e30: 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c  nteger.** [resul
4e40: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4e50: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4e60: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4e70: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4e80: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4e90: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4ea0: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4eb0: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
4ec0: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4ed0: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4ee0: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4ef0: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4f00: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4f10: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4f20: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4f30: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4f40: 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e  3.8 [dateof:3.3.
4f50: 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29  8].** and later)
4f60: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
4f70: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
4f80: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
4f90: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
4fa0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
4fb0: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
4fc0: 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65  errors. These [e
4fd0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4fe0: 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65  odes] are enable
4ff0: 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
5000: 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61   on a per databa
5010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  se connection ba
5020: 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  sis using the.**
5030: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
5040: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
5050: 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65  )] API.  Or, the
5060: 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66   extended code f
5070: 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72  or.** the most r
5080: 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20  ecent error can 
5090: 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e  be obtained usin
50a0: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  g.** [sqlite3_ex
50b0: 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
50c0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
50d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
50e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
50f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
5100: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5110: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
5120: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
5130: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
5140: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5150: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
5160: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5170: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
5180: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5190: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
51a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51b0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
51c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51d0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
51e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51f0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
5200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5210: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
5220: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5230: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
5240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5250: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
5260: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5270: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
5280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5290: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
52a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52b0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
52c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
52d0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
52e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52f0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
5300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5310: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
5320: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5330: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
5340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5350: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
5360: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5370: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
5380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5390: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
53a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
53b0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
53c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53d0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
53e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
53f0: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
5400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5410: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
5420: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
5430: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
5440: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5450: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
5460: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5470: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
5480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5490: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
54a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54b0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
54c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
54d0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
54e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54f0: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
5500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5510: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
5520: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5530: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
5540: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5550: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
5560: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5570: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
5580: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5590: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
55a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
55b0: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
55c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
55d0: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
55e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
55f0: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5610: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5620: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5630: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5650: 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20  R_DELETE_NOENT  
5660: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5670: 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65  R | (23<<8)).#de
5680: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5690: 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  R_MMAP          
56a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
56b0: 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65  R | (24<<8)).#de
56c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
56d0: 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20  R_GETTEMPPATH   
56e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
56f0: 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65  R | (25<<8)).#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5710: 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  R_CONVPATH      
5720: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5730: 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65  R | (26<<8)).#de
5740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5750: 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20  R_VNODE         
5760: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5770: 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65  R | (27<<8)).#de
5780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5790: 52 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20  R_AUTH          
57a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
57b0: 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65  R | (28<<8)).#de
57c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
57d0: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
57e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
57f0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
5800: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5810: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5820: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5830: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5850: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5860: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5870: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5880: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5890: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
58a0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
58b0: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
58c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58d0: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
58e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
58f0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5900: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5910: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5920: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5930: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5940: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5950: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5960: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5970: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5980: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5990: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
59a0: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
59b0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
59c0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
59d0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
59e0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
59f0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5a00: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5a20: 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20  LY_CANTLOCK     
5a30: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5a40: 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  LY | (2<<8)).#de
5a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5a60: 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  ONLY_ROLLBACK   
5a70: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5a80: 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23  ONLY | (3<<8)).#
5a90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5aa0: 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20  ADONLY_DBMOVED  
5ab0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5ac0: 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29  ADONLY | (4<<8))
5ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ae0: 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20  ABORT_ROLLBACK  
5af0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5b00: 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a  ABORT | (2<<8)).
5b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b20: 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20  ONSTRAINT_CHECK 
5b30: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5b40: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c  ONSTRAINT | (1<<
5b50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b60: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f  TE_CONSTRAINT_CO
5b70: 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49  MMITHOOK   (SQLI
5b80: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b90: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5ba0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bb0: 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28  T_FOREIGNKEY   (
5bc0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bd0: 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  T | (3<<8)).#def
5be0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bf0: 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20  RAINT_FUNCTION  
5c00: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c10: 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a  RAINT | (4<<8)).
5c20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c30: 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c  ONSTRAINT_NOTNUL
5c40: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  L      (SQLITE_C
5c50: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c  ONSTRAINT | (5<<
5c60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c70: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52  TE_CONSTRAINT_PR
5c80: 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49  IMARYKEY   (SQLI
5c90: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5ca0: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
5cb0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5cc0: 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28  T_TRIGGER      (
5cd0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ce0: 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  T | (7<<8)).#def
5cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5d00: 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20  RAINT_UNIQUE    
5d10: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5d20: 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a  RAINT | (8<<8)).
5d30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5d40: 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20  ONSTRAINT_VTAB  
5d50: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5d60: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c  ONSTRAINT | (9<<
5d70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d80: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f  TE_CONSTRAINT_RO
5d90: 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  WID        (SQLI
5da0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28  TE_CONSTRAINT |(
5db0: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5dc0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45  SQLITE_NOTICE_RE
5dd0: 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28  COVER_WAL      (
5de0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20  SQLITE_NOTICE | 
5df0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5e00: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45  SQLITE_NOTICE_RE
5e10: 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28  COVER_ROLLBACK (
5e20: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20  SQLITE_NOTICE | 
5e30: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5e40: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41  SQLITE_WARNING_A
5e50: 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28  UTOINDEX       (
5e60: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c  SQLITE_WARNING |
5e70: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5e80: 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45   SQLITE_AUTH_USE
5e90: 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  R               
5ea0: 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28  (SQLITE_AUTH | (
5eb0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5ec0: 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45  QLITE_OK_LOAD_PE
5ed0: 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53  RMANENTLY     (S
5ee0: 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38  QLITE_OK | (1<<8
5ef0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
5f00: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
5f10: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
5f20: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
5f30: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
5f40: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
5f50: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
5f60: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5f70: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5f80: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
5f90: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
5fa0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5fb0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
5fc0: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64  n] method..*/.#d
5fd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5fe0: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
5ff0: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
6000: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6010: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6030: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
6040: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
6050: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6060: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6080: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
6090: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
60a0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
60b0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
60c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
60d0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
60e0: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
60f0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6100: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6110: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
6120: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
6130: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6140: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6150: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
6160: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
6170: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6190: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20  N_URI           
61a0: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f     0x00000040  /
61b0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
61c0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
61e0: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20  N_MEMORY        
61f0: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f     0x00000080  /
6200: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6210: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6220: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6230: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
6240: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
6250: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6260: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6270: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
6280: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
6290: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
62a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
62b0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
62c0: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
62d0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
62e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
62f0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
6300: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
6310: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6330: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
6340: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
6350: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6370: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
6380: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
6390: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
63a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
63b0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
63c0: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
63d0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
63e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
63f0: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
6400: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
6410: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6420: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6440: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
6450: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
6460: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6470: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6480: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6490: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
64a0: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
64b0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
64c0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
64d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
64e0: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
64f0: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
6500: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6510: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6530: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  N_WAL           
6540: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f     0x00080000  /
6550: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  * VFS only */../
6560: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
6570: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6580: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
6590: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
65a0: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
65b0: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
65c0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
65d0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
65e0: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
65f0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
6600: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
6610: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
6620: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
6630: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
6640: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
6650: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
6660: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
6670: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
6680: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
6690: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
66a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
66b0: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
66c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
66d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
66e0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
66f0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
6700: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
6710: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6720: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6730: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6740: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6750: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6760: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6770: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6780: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6790: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
67a0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
67b0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
67c0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
67d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
67e0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
67f0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
6800: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6810: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
6820: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6830: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6840: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6850: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6860: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6870: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6880: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6890: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
68a0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
68b0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
68c0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
68d0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
68e0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
68f0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
6900: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6910: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
6920: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
6930: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
6940: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
6950: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
6960: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
6970: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
6980: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
6990: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
69a0: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
69b0: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
69c0: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
69d0: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
69e0: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
69f0: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
6a00: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
6a10: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
6a20: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ed.  The SQLITE_
6a30: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
6a40: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66  E_WHEN_OPEN.** f
6a50: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6a60: 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74  at a file cannot
6a70: 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e   be deleted when
6a80: 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53   open.  The.** S
6a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6aa0: 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63  TABLE flag indic
6ab0: 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69  ates that the fi
6ac0: 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64  le is on.** read
6ad0: 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20  -only media and 
6ae0: 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
6af0: 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73  d even by proces
6b00: 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76  ses with.** elev
6b10: 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e  ated privileges.
6b20: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6b30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6b50: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
6b60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b70: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
6b80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6b90: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6ba0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
6bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6bc0: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
6bd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6be0: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
6bf0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
6c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c10: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
6c20: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c30: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
6c40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6c50: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
6c60: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
6c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c80: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
6c90: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6ca0: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
6cb0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6cc0: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
6cd0: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
6ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
6d00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
6d10: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6d20: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6d30: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
6d40: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
6d50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6d60: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
6d70: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
6d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d90: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
6da0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
6db0: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
6dc0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
6dd0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
6de0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23      0x00001000.#
6df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6e00: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20  CAP_IMMUTABLE   
6e10: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6e20: 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  02000../*.** CAP
6e30: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
6e40: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
6e50: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
6e60: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
6e70: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6e80: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
6e90: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
6ea0: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
6eb0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
6ec0: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
6ed0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
6ee0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
6ef0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6f00: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
6f10: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
6f20: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
6f30: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
6f40: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
6f50: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
6f60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6f70: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
6f80: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
6f90: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
6fa0: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
6fb0: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
6fc0: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
6fd0: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
6fe0: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
6ff0: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
7000: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
7010: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7020: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
7030: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
7040: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
7050: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
7060: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
7070: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
7080: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7090: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
70a0: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
70b0: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
70c0: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
70d0: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
70e0: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
70f0: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
7100: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
7110: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
7120: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
7130: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
7140: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7150: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
7160: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
7170: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
7180: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
7190: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
71a0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
71b0: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
71c0: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
71d0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
71e0: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
71f0: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
7200: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
7210: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7220: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
7230: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
7240: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
7250: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7260: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
7270: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7280: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
7290: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
72a0: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
72b0: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
72c0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
72d0: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
72e0: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
72f0: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
7300: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
7310: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
7320: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7330: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7340: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
7350: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
7360: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
7370: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
7380: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
7390: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
73a0: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
73b0: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
73c0: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
73d0: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
73e0: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
73f0: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
7400: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
7410: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
7420: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
7430: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7440: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
7450: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
7460: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
7470: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
7480: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
7490: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
74a0: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
74b0: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
74c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
74d0: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
74e0: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
74f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7500: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7510: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
7520: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
7530: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
7540: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7550: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
7560: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
7570: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
7580: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
7590: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
75a0: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
75b0: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
75c0: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
75d0: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
75e0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
75f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
7600: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
7610: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
7620: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
7630: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
7640: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
7650: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
7660: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
7670: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
7680: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7690: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
76a0: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
76b0: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
76c0: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
76d0: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
76e0: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
76f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
7700: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
7710: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7720: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
7730: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7740: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
7750: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
7760: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
7770: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
7780: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7790: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
77a0: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
77b0: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
77c0: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
77d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
77e0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
77f0: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
7800: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7810: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
7820: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
7830: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
7840: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7850: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
7860: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
7870: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
7880: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
7890: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
78a0: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
78b0: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
78c0: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
78d0: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
78e0: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
78f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
7900: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
7910: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7920: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7930: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
7940: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7950: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
7960: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
7970: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
7980: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
7990: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
79a0: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
79b0: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
79c0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
79d0: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
79e0: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
79f0: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
7a00: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
7a10: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
7a20: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
7a30: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
7a40: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
7a50: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
7a60: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
7a70: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7a80: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
7a90: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
7aa0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7ab0: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
7ac0: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
7ad0: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
7ae0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
7af0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
7b00: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
7b10: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
7b20: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
7b30: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
7b40: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
7b50: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
7b60: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
7b70: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
7b80: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
7b90: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
7ba0: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
7bb0: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
7bc0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
7bd0: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
7be0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
7bf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
7c00: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
7c10: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
7c20: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
7c30: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
7c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7c50: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
7c60: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
7c70: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
7c80: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
7c90: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
7ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
7cb0: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
7cc0: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
7cd0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
7ce0: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
7cf0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
7d00: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
7d10: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
7d20: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
7d30: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
7d40: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
7d50: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
7d60: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
7d70: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
7d80: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
7d90: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
7da0: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
7db0: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
7dc0: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
7dd0: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
7de0: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
7df0: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
7e00: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
7e10: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
7e20: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
7e30: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
7e40: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
7e50: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
7e60: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
7e70: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
7e80: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
7e90: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
7ea0: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
7eb0: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
7ec0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
7ed0: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
7ee0: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
7ef0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
7f00: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
7f10: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
7f20: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
7f30: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
7f40: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
7f50: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
7f60: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
7f70: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
7f80: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
7f90: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
7fa0: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
7fb0: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
7fc0: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
7fd0: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
7fe0: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
7ff0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
8000: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
8010: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
8020: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
8030: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
8040: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
8050: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
8060: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
8070: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
8080: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
8090: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
80a0: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
80b0: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  [file control op
80c0: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20  codes | list of 
80d0: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
80e0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
80f0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
8100: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
8110: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
8120: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
8130: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
8140: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
8150: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
8160: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
8170: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
8180: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
8190: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
81a0: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
81b0: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
81c0: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
81d0: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
81e0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
81f0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8200: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
8210: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
8220: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
8230: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
8240: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
8250: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
8260: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
8270: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
8280: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
8290: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
82a0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
82b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
82c0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
82d0: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
82e0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
82f0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
8300: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
8310: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
8320: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
8330: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
8340: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8350: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8360: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8370: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8380: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8390: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
83a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
83c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
83e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
8400: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8410: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
8420: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8430: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
8440: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8450: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8460: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8470: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8480: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  UENTIAL].** <li>
8490: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55   [SQLITE_IOCAP_U
84a0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
84b0: 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OPEN].** <li> [S
84c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
84d0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
84e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
84f0: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
8500: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8510: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8520: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8530: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8540: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8550: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
8560: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8570: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
8580: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
8590: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
85a0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
85b0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
85c0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
85d0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
85e0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
85f0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8600: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8610: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8620: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8630: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8640: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8650: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
8660: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
8670: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
8680: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
8690: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
86a0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
86b0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
86c0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
86d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
86e0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
86f0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8700: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8710: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8720: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8730: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8740: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8750: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
8760: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
8770: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
8780: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
8790: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
87a0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
87b0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
87c0: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
87d0: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
87e0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
87f0: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8800: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8810: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8820: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8830: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8840: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8850: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
8860: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
8870: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8880: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
8890: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
88a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
88b0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
88c0: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
88d0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
88e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
88f0: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8900: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8910: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8920: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8930: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8940: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8950: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8960: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8970: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
8980: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
8990: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
89a0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
89b0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
89c0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
89d0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
89e0: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
89f0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8a00: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8a10: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8a20: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8a30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8a40: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8a50: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8a60: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
8a70: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8a80: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
8a90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
8aa0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
8ab0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8ac0: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8ad0: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8ae0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8af0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8b00: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8b10: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8b20: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8b30: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8b40: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8b50: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
8b60: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8b70: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
8b80: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
8b90: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
8ba0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
8bb0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8bc0: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8bd0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8be0: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8bf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8c00: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8c10: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8c20: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8c30: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8c40: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8c50: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
8c60: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
8c70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8c80: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8c90: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
8ca0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
8cb0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8cc0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8cd0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8ce0: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8cf0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8d00: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8d10: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8d20: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8d30: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8d40: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8d50: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
8d60: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
8d70: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
8d80: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
8d90: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
8da0: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
8db0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8dc0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8dd0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8de0: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8df0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8e00: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8e10: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8e20: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8e30: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8e40: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8e50: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8e60: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8e70: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8e80: 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54  LOCKSTATE]].** T
8e90: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8ea0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
8eb0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
8ec0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
8ed0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
8ee0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8ef0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
8f00: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8f10: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8f20: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
8f30: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
8f40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8f50: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
8f60: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
8f70: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
8f80: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
8f90: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8fa0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
8fb0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
8fc0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
8fd0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
8fe0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8ff0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
9000: 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76  g and is only av
9010: 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65  ailable when the
9020: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
9030: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
9040: 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
9050: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9060: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
9070: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9080: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
9090: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
90a0: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
90b0: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
90c0: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
90d0: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
90e0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
90f0: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
9100: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
9110: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
9120: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
9130: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
9140: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
9150: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
9160: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
9170: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
9180: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
9190: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
91a0: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
91b0: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
91c0: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
91d0: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
91e0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
91f0: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
9200: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9210: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
9220: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9230: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
9240: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9250: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
9260: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
9270: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
9280: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9290: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
92a0: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
92b0: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
92c0: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
92d0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
92e0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
92f0: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
9300: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
9310: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
9320: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
9330: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
9340: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
9350: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
9360: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
9370: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
9380: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
9390: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
93a0: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
93b0: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
93c0: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
93d0: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
93e0: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
93f0: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
9400: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
9410: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
9420: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9430: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9440: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9450: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
9460: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
9470: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
9480: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
9490: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
94a0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
94b0: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c  nection.  See al
94c0: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  so [SQLITE_FCNTL
94d0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
94e0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
94f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
9500: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  NAL_POINTER]].**
9510: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9520: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
9530: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
9540: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
9550: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
9560: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9570: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
9580: 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e  d with the journ
9590: 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a  al file (either.
95a0: 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b  ** the [rollback
95b0: 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65   journal] or the
95c0: 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f   [write-ahead lo
95d0: 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63  g]) for a partic
95e0: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
95f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9600: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
9610: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9620: 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  R]..**.** <li>[[
9630: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9640: 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e  C_OMITTED]].** N
9650: 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e  o longer in use.
9660: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9670: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d  ITE_FCNTL_SYNC]]
9680: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9690: 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f  FCNTL_SYNC] opco
96a0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
96b0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
96c0: 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74  Lite and.** sent
96d0: 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65   to the VFS imme
96e0: 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74  diately before t
96f0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
9700: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a  is invoked on a.
9710: 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ** database file
9720: 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c   descriptor. Or,
9730: 20 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65   if the xSync me
9740: 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f  thod is not invo
9750: 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20  ked .** because 
9760: 74 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e  the user has con
9770: 66 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77  figured SQLite w
9780: 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20  ith .** [PRAGMA 
9790: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52  synchronous | PR
97a0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
97b0: 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f  =OFF] it is invo
97c0: 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a  ked in place .**
97d0: 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65   of the xSync me
97e0: 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61  thod. In most ca
97f0: 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72  ses, the pointer
9800: 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
9810: 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69   with.** this fi
9820: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55  le-control is NU
9830: 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20  LL. However, if 
9840: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9850: 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65  e is being synce
9860: 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  d.** as part of 
9870: 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65  a multi-database
9880: 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67   commit, the arg
9890: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20  ument points to 
98a0: 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
98b0: 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
98c0: 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61  ining the transa
98d0: 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f  ctions master-jo
98e0: 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e  urnal file name.
98f0: 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20   VFSes that .** 
9900: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
9910: 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73   signal should s
9920: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
9930: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
9940: 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f  ications .** sho
9950: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71  uld not call [sq
9960: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9970: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9980: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
9990: 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75  so may .** disru
99a0: 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  pt the operation
99b0: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
99c0: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
99d0: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
99e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
99f0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
9a00: 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68  PHASETWO]].** Th
9a10: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9a20: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
9a30: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
9a40: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
9a50: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
9a60: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
9a70: 20 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63   after a transac
9a80: 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f  tion has been co
9a90: 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74  mmitted immediat
9aa0: 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72  ely.** but befor
9ab0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
9ac0: 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65  s unlocked. VFSe
9ad0: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65  s that do not ne
9ae0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a  ed this signal.*
9af0: 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  * should silentl
9b00: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
9b10: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
9b20: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
9b30: 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ll.** [sqlite3_f
9b40: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
9b50: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
9b60: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
9b70: 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20  disrupt the .** 
9b80: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
9b90: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9ba0: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
9bb0: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9bc0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9bd0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
9be0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9bf0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9c00: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
9c10: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
9c20: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
9c30: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
9c40: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
9c50: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
9c60: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
9c70: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
9c80: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
9c90: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
9ca0: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
9cb0: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
9cc0: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
9cd0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9ce0: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
9cf0: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
9d00: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
9d10: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
9d20: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
9d30: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
9d40: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
9d50: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9d60: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
9d70: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
9d80: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
9d90: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
9da0: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
9db0: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
9dc0: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
9dd0: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
9de0: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
9df0: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
9e00: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
9e10: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
9e20: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
9e30: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
9e40: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
9e50: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
9e60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
9e70: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
9e80: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
9e90: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
9ea0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
9eb0: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
9ec0: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
9ed0: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 73 20  irst integer is 
9ee0: 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f  the new retry co
9ef0: 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  unt and the seco
9f00: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73  nd.** integer is
9f10: 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20   the delay.  If 
9f20: 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69  either integer i
9f30: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
9f40: 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
9f50: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62  is not changed b
9f60: 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70  ut instead the p
9f70: 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
9f80: 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72  at setting is wr
9f90: 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68  itten.** into th
9fa0: 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61  e array entry, a
9fb0: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72  llowing the curr
9fc0: 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e  ent retry settin
9fd0: 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65  gs to be.** inte
9fe0: 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a  rrogated.  The z
9ff0: 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  DbName parameter
a000: 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
a010: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a020: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
a030: 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  L]].** ^The [SQL
a040: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a050: 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73  T_WAL] opcode is
a060: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
a070: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
a080: 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57  sistent [WAL | W
a090: 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20  rite Ahead Log] 
a0a0: 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66  setting.  By def
a0b0: 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69  ault, the auxili
a0c0: 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65  ary.** write ahe
a0d0: 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65  ad log and share
a0e0: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75  d memory files u
a0f0: 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74  sed for transact
a100: 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61  ion control.** a
a110: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
a120: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
a130: 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74  e latest connect
a140: 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62  ion to the datab
a150: 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20  ase.** closes.  
a160: 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65  Setting persiste
a170: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73  nt WAL mode caus
a180: 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74  es those files t
a190: 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a  o persist after.
a1a0: 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69  ** close.  Persi
a1b0: 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20  sting the files 
a1c0: 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f  is useful when o
a1d0: 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74  ther processes t
a1e0: 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61  hat do not.** ha
a1f0: 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73  ve write permiss
a200: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63  ion on the direc
a210: 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  tory containing 
a220: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a230: 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61  e want.** to rea
a240: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  d the database f
a250: 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20  ile, as the WAL 
a260: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
a270: 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69  y files must exi
a280: 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66  st.** in order f
a290: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
a2a0: 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20  to be readable. 
a2b0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
a2c0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
a2d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a2e0: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
a2f0: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
a300: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
a310: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
a320: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
a330: 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65  disable persiste
a340: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31  nt WAL mode or 1
a350: 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69   to enable persi
a360: 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64  stent.** WAL mod
a370: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
a380: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
a390: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
a3a0: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
a3b0: 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74  t.** WAL persist
a3c0: 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  ence setting..**
a3d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a3e0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a3f0: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
a400: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a410: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
a420: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a430: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
a440: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
a450: 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73  rsistent "powers
a460: 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f  afe-overwrite" o
a470: 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67  r "PSOW" setting
a480: 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74  .  The PSOW sett
a490: 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65  ing.** determine
a4a0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f  s the [SQLITE_IO
a4b0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
a4c0: 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20  ERWRITE] bit of 
a4d0: 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68  the.** xDeviceCh
a4e0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
a4f0: 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74  thods. The fourt
a500: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a510: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a520: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a530: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a540: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a550: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a560: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a570: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65   0 to disable ze
a580: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f  ro-damage mode o
a590: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65  r 1 to enable ze
a5a0: 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64  ro-damage.** mod
a5b0: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
a5c0: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
a5d0: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
a5e0: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
a5f0: 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65  t.** zero-damage
a600: 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a   mode setting..*
a610: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a620: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a630: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a640: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a650: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  ITE] opcode is i
a660: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a670: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a   after opening.*
a680: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61  * a write transa
a690: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74  ction to indicat
a6a0: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69  e that, unless i
a6b0: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t is rolled back
a6c0: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61   for some.** rea
a6d0: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20  son, the entire 
a6e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
a6f0: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ll be overwritte
a700: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  n by the current
a710: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e   .** transaction
a720: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62  . This is used b
a730: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69  y VACUUM operati
a740: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ons..**.** <li>[
a750: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a760: 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  SNAME]].** ^The 
a770: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a780: 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61  SNAME] opcode ca
a790: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
a7a0: 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
a7b0: 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20  .** all [VFSes] 
a7c0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b  in the VFS stack
a7d0: 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65  .  The names are
a7e0: 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d   of all VFS shim
a7f0: 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e  s and the.** fin
a800: 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20  al bottom-level 
a810: 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20  VFS are written 
a820: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
a830: 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
a840: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
a850: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20   and the result 
a860: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  is stored in the
a870: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a   char* variable.
a880: 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72  ** that the four
a890: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
a8a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a8b0: 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20  ntrol()] points 
a8c0: 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65  to..** The calle
a8d0: 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  r is responsible
a8e0: 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65   for freeing the
a8f0: 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e   memory when don
a900: 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61  e.  As with.** a
a910: 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ll file-control 
a920: 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69  actions, there i
a930: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74  s no guarantee t
a940: 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63  hat this will ac
a950: 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79  tually.** do any
a960: 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20  thing.  Callers 
a970: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a  should initializ
a980: 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  e the char* vari
a990: 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  able to a NULL.*
a9a0: 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73  * pointer in cas
a9b0: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
a9c0: 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  rol is not imple
a9d0: 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69  mented.  This fi
a9e0: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73  le-control.** is
a9f0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69   intended for di
aa00: 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c  agnostic use onl
aa10: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
aa20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
aa30: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68  POINTER]].** ^Th
aa40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa50: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  VFS_POINTER] opc
aa60: 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e  ode finds a poin
aa70: 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c  ter to the top-l
aa80: 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20  evel.** [VFSes] 
aa90: 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65  currently in use
aaa0: 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e  .  ^(The argumen
aab0: 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65  t X in.** sqlite
aac0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64  3_file_control(d
aad0: 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  b,SQLITE_FCNTL_V
aae0: 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75  FS_POINTER,X) mu
aaf0: 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65  st be.** of type
ab00: 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20   "[sqlite3_vfs] 
ab10: 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64  **".  This opcod
ab20: 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a  es will set *X.*
ab30: 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74  * to a pointer t
ab40: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20  o the top-level 
ab50: 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20  VFS.)^.** ^When 
ab60: 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70  there are multip
ab70: 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20  le VFS shims in 
ab80: 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20  the stack, this 
ab90: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65  opcode finds the
aba0: 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73  .** upper-most s
abb0: 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  him only..**.** 
abc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
abd0: 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e  TL_PRAGMA]].** ^
abe0: 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47  Whenever a [PRAG
abf0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  MA] statement is
ac00: 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c   parsed, an [SQL
ac10: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ac20: 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  ] .** file contr
ac30: 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68  ol is sent to th
ac40: 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e open [sqlite3_
ac50: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72  file] object cor
ac60: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f  responding.** to
ac70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
ac80: 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  le to which the 
ac90: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
aca0: 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72   refers. ^The ar
acb0: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
acc0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
acd0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
ace0: 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20  rol is an array 
acf0: 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  of.** pointers t
ad00: 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a  o strings (char*
ad10: 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  *) in which the 
ad20: 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f  second element o
ad30: 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69  f the array.** i
ad40: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
ad50: 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65  e pragma and the
ad60: 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69   third element i
ad70: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
ad80: 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20  o the.** pragma 
ad90: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70  or NULL if the p
ada0: 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67  ragma has no arg
adb0: 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e  ument.  ^The han
adc0: 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b  dler for an.** [
add0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ade0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
adf0: 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79  l can optionally
ae00: 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20   make the first 
ae10: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  element.** of th
ae20: 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e  e char** argumen
ae30: 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  t point to a str
ae40: 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
ae50: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
ae60: 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20  tf()].** or the 
ae70: 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74  equivalent and t
ae80: 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  hat string will 
ae90: 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c  become the resul
aea0: 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  t of the pragma 
aeb0: 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  or.** the error 
aec0: 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70  message if the p
aed0: 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66  ragma fails. ^If
aee0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
aef0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
af00: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
af10: 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ns [SQLITE_NOTFO
af20: 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61  UND], then norma
af30: 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70  l .** [PRAGMA] p
af40: 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e  rocessing contin
af50: 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ues.  ^If the [S
af60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
af70: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
af80: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
af90: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68  ITE_OK], then th
afa0: 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73  e parser assumes
afb0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53   that the.** VFS
afc0: 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65   has handled the
afd0: 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61   PRAGMA itself a
afe0: 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65  nd the parser ge
aff0: 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a  nerates a no-op.
b000: 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
b010: 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20  ement if result 
b020: 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20  string is NULL, 
b030: 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e 73 20  or that returns 
b040: 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
b050: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69   result string i
b060: 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20  f the string is 
b070: 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66  non-NULL..** ^If
b080: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b090: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b0a0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a  control returns.
b0b0: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f  ** any result co
b0c0: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  de other than [S
b0d0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51  QLITE_OK] or [SQ
b0e0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
b0f0: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  that means.** th
b100: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75  at the VFS encou
b110: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20  ntered an error 
b120: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74  while handling t
b130: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20  he [PRAGMA] and 
b140: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69  the.** compilati
b150: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41  on of the PRAGMA
b160: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65   fails with an e
b170: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c  rror.  ^The [SQL
b180: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b190: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
b1a0: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20  l occurs at the 
b1b0: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61  beginning of pra
b1c0: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  gma statement an
b1d0: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a  alysis and so.**
b1e0: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f   it is able to o
b1f0: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e  verride built-in
b200: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
b210: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ents..**.** <li>
b220: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
b230: 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20  USYHANDLER]].** 
b240: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
b250: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a  TL_BUSYHANDLER].
b260: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b270: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62  may be invoked b
b280: 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20  y SQLite on the 
b290: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61  database file ha
b2a0: 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20  ndle.** shortly 
b2b0: 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e  after it is open
b2c0: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  ed in order to p
b2d0: 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20  rovide a custom 
b2e0: 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a  VFS with access.
b2f0: 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63  ** to the connec
b300: 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c  tions busy-handl
b310: 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65  er callback. The
b320: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20   argument is of 
b330: 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a  type (void **).*
b340: 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20  * - an array of 
b350: 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c  two (void *) val
b360: 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28  ues. The first (
b370: 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79  void *) actually
b380: 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20   points.** to a 
b390: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
b3a0: 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a   (int (*)(void *
b3b0: 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  )). In order to 
b3c0: 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65  invoke the conne
b3d0: 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68  ctions.** busy-h
b3e0: 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e  andler, this fun
b3f0: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ction should be 
b400: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65  invoked with the
b410: 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29   second (void *)
b420: 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79   in.** the array
b430: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67   as the only arg
b440: 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74  ument. If it ret
b450: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
b460: 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f  hen the operatio
b470: 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
b480: 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65  etried. If it re
b490: 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
b4a0: 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c  custom VFS shoul
b4b0: 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a  d abandon the.**
b4c0: 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
b4d0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
b4e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b4f0: 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  PFILENAME]].** ^
b500: 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  Application can 
b510: 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49  invoke the [SQLI
b520: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b530: 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74  ENAME] file-cont
b540: 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53  rol.** to have S
b550: 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61  QLite generate a
b560: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b570: 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65  lename using the
b580: 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
b590: 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64  that is followed
b5a0: 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20   to generate.** 
b5b0: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
b5c0: 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62  mes for TEMP tab
b5d0: 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e  les and other in
b5e0: 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68  ternal uses.  Th
b5f0: 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  e.** argument sh
b600: 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a  ould be a char**
b610: 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66   which will be f
b620: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66  illed with the f
b630: 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74  ilename.** writt
b640: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
b650: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b660: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
b670: 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f    The caller sho
b680: 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73  uld.** invoke [s
b690: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
b6a0: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20  n the result to 
b6b0: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c  avoid a memory l
b6c0: 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  eak..**.** <li>[
b6d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
b6e0: 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  AP_SIZE]].** The
b6f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
b700: 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
b710: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74  ontrol is used t
b720: 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74  o query or set t
b730: 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75  he.** maximum nu
b740: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68  mber of bytes th
b750: 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  at will be used 
b760: 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65  for memory-mappe
b770: 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72  d I/O..** The ar
b780: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
b790: 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f  ter to a value o
b7a0: 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69  f type sqlite3_i
b7b0: 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20  nt64 that.** is 
b7c0: 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69  an advisory maxi
b7d0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b7e0: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20  tes in the file 
b7f0: 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20  to memory map.  
b800: 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  The.** pointer i
b810: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
b820: 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65  th the old value
b830: 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  .  The limit is 
b840: 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a  not changed if.*
b850: 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67  * the value orig
b860: 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74  inally pointed t
b870: 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61  o is negative, a
b880: 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e  nd so the curren
b890: 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20  t limit .** can 
b8a0: 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61  be queried by pa
b8b0: 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74  ssing in a point
b8c0: 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65  er to a negative
b8d0: 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a   number.  This.*
b8e0: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  * file-control i
b8f0: 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
b900: 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  y to implement [
b910: 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
b920: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
b930: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b940: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b950: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  TE_FCNTL_TRACE] 
b960: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f  file control pro
b970: 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69  vides advisory i
b980: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f  nformation.** to
b990: 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77   the VFS about w
b9a0: 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c  hat the higher l
b9b0: 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c  ayers of the SQL
b9c0: 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f  ite stack are do
b9d0: 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c  ing..** This fil
b9e0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b9f0: 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63  d by some VFS ac
ba00: 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b  tivity tracing [
ba10: 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  shims]..** The a
ba20: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72  rgument is a zer
ba30: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
ba40: 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79  ing.  Higher lay
ba50: 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51  ers in the.** SQ
ba60: 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67  Lite stack may g
ba70: 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65  enerate instance
ba80: 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63  s of this file c
ba90: 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65  ontrol if.** the
baa0: 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e   [SQLITE_USE_FCN
bab0: 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  TL_TRACE] compil
bac0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
bad0: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
bae0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
baf0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a  TL_HAS_MOVED]].*
bb00: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bb10: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66  NTL_HAS_MOVED] f
bb20: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65  ile control inte
bb30: 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d  rprets its argum
bb40: 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e  ent as a.** poin
bb50: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
bb60: 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20  r and it writes 
bb70: 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74  a boolean into t
bb80: 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65  hat integer depe
bb90: 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74  nding.** on whet
bba0: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66  her or not the f
bbb0: 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e  ile has been ren
bbc0: 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20  amed, moved, or 
bbd0: 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74  deleted since it
bbe0: 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70  .** was first op
bbf0: 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ened..**.** <li>
bc00: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
bc10: 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d  IN32_GET_HANDLE]
bc20: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bc30: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
bc40: 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20  _HANDLE] opcode 
bc50: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
bc60: 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64  btain the.** und
bc70: 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66  erlying native f
bc80: 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63  ile handle assoc
bc90: 69 61 74 65 64 20 77 69 74 68 20 61 20 66 69 6c  iated with a fil
bca0: 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20  e handle.  This 
bcb0: 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20  file.** control 
bcc0: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
bcd0: 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69  rgument as a poi
bce0: 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65  nter to a native
bcf0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64   file handle and
bd00: 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65 20 72  .** writes the r
bd10: 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74  esulting value t
bd20: 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  here..**.** <li>
bd30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
bd40: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
bd50: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bd60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
bd70: 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20  _HANDLE] opcode 
bd80: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
bd90: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
bda0: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
bdb0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
bdc0: 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68  ethod to swap th
bdd0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69  e file handle wi
bde0: 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f  th the one.** po
bdf0: 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
be00: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20  pArg argument.  
be10: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20  This capability 
be20: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
be30: 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e  esting.** and on
be40: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
be50: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
be60: 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66  LITE_TEST is def
be70: 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ined..**.** <li>
be80: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
be90: 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68  AL_BLOCK]].** Th
bea0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
beb0: 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20  WAL_BLOCK] is a 
bec0: 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46  signal to the VF
bed0: 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 74 20  S layer that it 
bee0: 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61  might.** be adva
bef0: 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63  ntageous to bloc
bf00: 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41  k on the next WA
bf10: 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f  L lock if the lo
bf20: 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69  ck is not immedi
bf30: 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62  ately.** availab
bf40: 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62  le.  The WAL sub
bf50: 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 74 68  system issues th
bf60: 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67  is signal during
bf70: 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73   rare.** circums
bf80: 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20  tances in order 
bf90: 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d  to fix a problem
bfa0: 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 20 69   with priority i
bfb0: 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70  nversion..** App
bfc0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
bfd0: 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73   <em>not</em> us
bfe0: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
bff0: 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  rol..**.** <li>[
c000: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
c010: 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  PVFS]].** The [S
c020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
c030: 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d  FS] opcode is im
c040: 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70  plemented by zip
c050: 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74  vfs only. All ot
c060: 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c  her.** VFS shoul
c070: 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  d return SQLITE_
c080: 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69  NOTFOUND for thi
c090: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  s opcode..**.** 
c0a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c0b0: 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20  TL_RBU]].** The 
c0c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
c0d0: 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70  U] opcode is imp
c0e0: 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20  lemented by the 
c0f0: 73 70 65 63 69 61 6c 20 56 46 53 20 75 73 65 64  special VFS used
c100: 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65   by.** the RBU e
c110: 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20  xtension only.  
c120: 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68  All other VFS sh
c130: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
c140: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a  TE_NOTFOUND for.
c150: 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  ** this opcode. 
c160: 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64   .** </ul>.*/.#d
c170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c180: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
c190: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
c1a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c1b0: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
c1c0: 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66  ILE       2.#def
c1d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c1e0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
c1f0: 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  LE       3.#defi
c200: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c210: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
c220: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
c230: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c240: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
c250: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
c260: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
c270: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
c280: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
c290: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
c2a0: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
c2b0: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
c2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
c2d0: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
c2e0: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
c2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c300: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
c310: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
c320: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
c330: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
c340: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
c350: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
c360: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
c370: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
c380: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
c390: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
c3a0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
c3b0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
c3c0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
c3d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c3e0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
c3f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
c400: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c410: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
c420: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
c430: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c440: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
c450: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64             16.#d
c460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c470: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  TL_MMAP_SIZE    
c480: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65            18.#de
c490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c4a0: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20  L_TRACE         
c4b0: 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66           19.#def
c4c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c4d0: 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20  _HAS_MOVED      
c4e0: 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69          20.#defi
c4f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c500: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
c510: 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e         21.#defin
c520: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
c530: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20  OMMIT_PHASETWO  
c540: 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65        22.#define
c550: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
c560: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20  N32_SET_HANDLE  
c570: 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20       23.#define 
c580: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
c590: 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  _BLOCK          
c5a0: 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53      24.#define S
c5b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
c5c0: 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20  FS              
c5d0: 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51     25.#define SQ
c5e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20  LITE_FCNTL_RBU  
c5f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c600: 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    26.#define SQL
c610: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
c620: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
c630: 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   27.#define SQLI
c640: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
c650: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c660: 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  28.#define SQLIT
c670: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45  E_FCNTL_WIN32_GE
c680: 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32  T_HANDLE       2
c690: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
c6a0: 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20  _FCNTL_PDB      
c6b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30                30
c6c0: 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20  ../* deprecated 
c6d0: 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  names */.#define
c6e0: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
c6f0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
c700: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
c710: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
c720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
c730: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c740: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
c750: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
c760: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
c770: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
c780: 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f           SQLITE_
c790: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
c7a0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
c7b0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
c7c0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
c7d0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
c7e0: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
c7f0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
c800: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
c810: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
c820: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
c830: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
c840: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
c850: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
c860: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
c870: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
c880: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
c890: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
c8a0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
c8b0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
c8c0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
c8d0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
c8e0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
c8f0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
c900: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
c910: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
c920: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
c930: 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c  API3REF: Loadabl
c940: 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e  e Extension Thun
c950: 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  k.**.** A pointe
c960: 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20  r to the opaque 
c970: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
c980: 69 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69  ines structure i
c990: 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  s passed as.** t
c9a0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
c9b0: 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e  er to entry poin
c9c0: 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20  ts of [loadable 
c9d0: 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68  extensions].  Th
c9e0: 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  is.** structure 
c9f0: 6d 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65  must be typedefe
ca00: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f  d in order to wo
ca10: 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c  rk around compil
ca20: 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f  er warnings.** o
ca30: 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73  n some platforms
ca40: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
ca50: 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
ca60: 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33  routines sqlite3
ca70: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a  _api_routines;..
ca80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ca90: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
caa0: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
cab0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
cac0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
cad0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
cae0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
caf0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
cb00: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
cb10: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
cb20: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
cb30: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
cb40: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
cb50: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
cb60: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
cb70: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
cb80: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
cb90: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
cba0: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
cbb0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
cbc0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
cbd0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
cbe0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
cbf0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
cc00: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
cc10: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
cc20: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
cc30: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
cc40: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
cc50: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
cc60: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
cc70: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
cc80: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
cc90: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
cca0: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
ccb0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
ccc0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
ccd0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
cce0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
ccf0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
cd00: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
cd10: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
cd20: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
cd30: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
cd40: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
cd50: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
cd60: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
cd70: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
cd80: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
cd90: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
cda0: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
cdb0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
cdc0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
cdd0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
cde0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
cdf0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
ce00: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
ce10: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
ce20: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
ce30: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
ce40: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
ce50: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
ce60: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
ce70: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
ce80: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
ce90: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
cea0: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
ceb0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
cec0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
ced0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
cee0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
cef0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
cf00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
cf10: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
cf20: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
cf30: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
cf40: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
cf50: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
cf60: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
cf70: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
cf80: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
cf90: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
cfa0: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
cfb0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
cfc0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
cfd0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
cfe0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
cff0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
d000: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
d010: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
d020: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
d030: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
d040: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
d050: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
d060: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
d070: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
d080: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
d090: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
d0a0: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
d0b0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
d0c0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
d0d0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
d0e0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
d0f0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
d100: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
d110: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
d120: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
d130: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
d140: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
d150: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
d160: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
d170: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
d180: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
d190: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
d1a0: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
d1b0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
d1c0: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
d1d0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
d1e0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
d1f0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
d200: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
d210: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
d220: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
d230: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
d240: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
d250: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
d260: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
d270: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
d280: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
d290: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
d2a0: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
d2b0: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
d2c0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
d2d0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
d2e0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
d2f0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
d300: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
d310: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
d320: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
d330: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
d340: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d350: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
d360: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
d370: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
d380: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
d390: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
d3a0: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
d3b0: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
d3c0: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
d3d0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
d3e0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
d3f0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
d400: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
d410: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
d420: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d430: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
d440: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
d450: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
d460: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
d470: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
d480: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
d490: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
d4a0: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
d4b0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
d4c0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
d4d0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
d4e0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
d4f0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
d500: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
d510: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
d520: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
d530: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
d540: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
d550: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
d560: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
d570: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
d580: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
d590: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
d5a0: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
d5b0: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
d5c0: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
d5d0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
d5e0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
d5f0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
d600: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
d610: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
d620: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
d630: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d640: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d650: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
d660: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d670: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
d680: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d690: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
d6a0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d6b0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
d6c0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d6d0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
d6e0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
d6f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
d700: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d710: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
d720: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
d730: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d740: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
d750: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
d760: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
d770: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
d780: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
d790: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
d7a0: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
d7b0: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
d7c0: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
d7d0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
d7e0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
d7f0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
d800: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
d810: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
d820: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
d830: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
d840: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
d850: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
d860: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
d870: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
d880: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
d890: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
d8a0: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
d8b0: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
d8c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
d8d0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
d8e0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
d8f0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
d900: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
d910: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
d920: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
d930: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
d940: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
d950: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
d960: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
d970: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
d980: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
d990: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
d9a0: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
d9b0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
d9c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
d9d0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
d9e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
d9f0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
da00: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
da10: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
da20: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
da30: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
da40: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
da50: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
da60: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
da70: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
da80: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
da90: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
daa0: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
dab0: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
dac0: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
dad0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
dae0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
daf0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
db00: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
db10: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
db20: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
db30: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
db40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
db50: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
db60: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
db70: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
db80: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
db90: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
dba0: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
dbb0: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
dbc0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
dbd0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
dbe0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
dbf0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
dc00: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
dc10: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
dc20: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
dc30: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
dc40: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
dc50: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
dc60: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
dc70: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
dc80: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
dc90: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
dca0: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
dcb0: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
dcc0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
dcd0: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
dce0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
dcf0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
dd00: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
dd10: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
dd20: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
dd30: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
dd40: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
dd50: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
dd60: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
dd70: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
dd80: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
dd90: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
dda0: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
ddb0: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
ddc0: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
ddd0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
dde0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
ddf0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
de00: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
de10: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
de20: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
de30: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
de40: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
de50: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
de60: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
de70: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
de80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
de90: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
dea0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
deb0: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
dec0: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
ded0: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
dee0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
def0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
df00: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
df10: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
df20: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
df30: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
df40: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
df50: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
df60: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
df70: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
df80: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
df90: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
dfa0: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
dfb0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
dfc0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
dfd0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
dfe0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
dff0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
e000: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
e010: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
e020: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
e030: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
e040: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
e050: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
e060: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
e070: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
e080: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
e090: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
e0a0: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
e0b0: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
e0c0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
e0d0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
e0e0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
e0f0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
e100: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
e110: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
e120: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
e130: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
e140: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
e150: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
e160: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
e170: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
e180: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
e190: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
e1a0: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
e1b0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
e1c0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
e1d0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
e1e0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
e1f0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
e200: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
e210: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
e220: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
e230: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
e240: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
e250: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
e260: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
e270: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
e280: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
e290: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
e2a0: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
e2b0: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
e2c0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
e2d0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
e2e0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
e2f0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
e300: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
e310: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
e320: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
e330: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
e340: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
e350: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
e360: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
e370: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
e380: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
e390: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
e3a0: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
e3b0: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
e3c0: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
e3d0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
e3e0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
e3f0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
e400: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
e410: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
e420: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
e430: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
e440: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
e450: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
e460: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
e470: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
e480: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
e490: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
e4a0: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
e4b0: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
e4c0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
e4d0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
e4e0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
e4f0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
e500: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
e510: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
e520: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
e530: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
e540: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
e550: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
e560: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
e570: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
e580: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
e590: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
e5a0: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
e5b0: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
e5c0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
e5d0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
e5e0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
e5f0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
e600: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
e610: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
e620: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
e630: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
e640: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
e650: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
e660: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
e670: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
e680: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
e690: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
e6a0: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
e6b0: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
e6c0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
e6d0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
e6e0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
e6f0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
e700: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
e710: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
e720: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
e730: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
e740: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
e750: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
e760: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
e770: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
e780: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
e790: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
e7a0: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
e7b0: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
e7c0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
e7d0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
e7e0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
e7f0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
e800: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
e810: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
e820: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
e830: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
e840: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
e850: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
e860: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
e870: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
e880: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
e890: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
e8a0: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
e8b0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
e8c0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
e8d0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
e8e0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
e8f0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
e900: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
e910: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
e920: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
e930: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
e940: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
e950: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
e960: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
e970: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
e980: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
e990: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
e9a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
e9b0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
e9c0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
e9d0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
e9e0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
e9f0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
ea00: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
ea10: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
ea20: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
ea30: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
ea40: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
ea50: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
ea60: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
ea70: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
ea80: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
ea90: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
eaa0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
eab0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
eac0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
ead0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
eae0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
eaf0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
eb00: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
eb10: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
eb20: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
eb30: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
eb40: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
eb50: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
eb60: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
eb70: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
eb80: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
eb90: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
eba0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
ebb0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
ebc0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
ebd0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ebe0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
ebf0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
ec00: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
ec10: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
ec20: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ec30: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ec40: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
ec50: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
ec60: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
ec70: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ec80: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
ec90: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
eca0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
ecb0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
ecc0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
ecd0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
ece0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
ecf0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ed00: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
ed10: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
ed20: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
ed30: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
ed40: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
ed50: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
ed60: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
ed70: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
ed80: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
ed90: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
eda0: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
edb0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
edc0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
edd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
ede0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
edf0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
ee00: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
ee10: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
ee20: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
ee30: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
ee40: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
ee50: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
ee60: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
ee70: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
ee80: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
ee90: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
eea0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
eeb0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
eec0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
eed0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
eee0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
eef0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
ef00: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
ef10: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ef20: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
ef30: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
ef40: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
ef50: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
ef60: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
ef70: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ef80: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
ef90: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
efa0: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
efb0: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
efc0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
efd0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
efe0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
eff0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
f000: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
f010: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f020: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
f030: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
f040: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
f050: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
f060: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
f070: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
f080: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
f090: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
f0a0: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
f0b0: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
f0c0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
f0d0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
f0e0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
f0f0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
f100: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
f110: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
f120: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
f130: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
f140: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
f150: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
f160: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
f170: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
f180: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
f190: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
f1a0: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
f1b0: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
f1c0: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
f1d0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f1e0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
f1f0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
f200: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
f210: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
f220: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
f230: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
f240: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
f250: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
f260: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
f270: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f280: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
f290: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
f2a0: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
f2b0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
f2c0: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
f2d0: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
f2e0: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
f2f0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
f300: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
f310: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
f320: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
f330: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
f340: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
f350: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
f360: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
f370: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
f380: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
f390: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
f3a0: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
f3b0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
f3c0: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
f3d0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
f3e0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f3f0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
f400: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
f410: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
f420: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f430: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
f440: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
f450: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
f460: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
f470: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
f480: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
f490: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
f4a0: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
f4b0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
f4c0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f4d0: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
f4e0: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
f4f0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
f500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
f510: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
f520: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
f530: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f540: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
f550: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
f560: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
f570: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
f580: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
f590: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
f5a0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
f5b0: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
f5c0: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
f5d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
f5e0: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
f5f0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
f600: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
f610: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
f620: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
f630: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
f640: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
f650: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
f660: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f670: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f680: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
f690: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f6a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f6b0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
f6c0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
f6d0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f6e0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
f6f0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
f700: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
f710: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
f720: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
f730: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
f740: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
f750: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
f760: 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
f770: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
f780: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
f790: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
f7a0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
f7b0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
f7c0: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
f7d0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
f7e0: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
f7f0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
f800: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
f810: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
f820: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
f830: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
f840: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
f850: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f860: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
f870: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
f880: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
f890: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
f8a0: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
f8b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
f8c0: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
f8d0: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
f8e0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
f8f0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
f900: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
f910: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
f920: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
f930: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
f940: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
f950: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
f960: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
f970: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
f980: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
f990: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
f9a0: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
f9b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f9c0: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
f9d0: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
f9e0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
f9f0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
fa00: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
fa10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fa20: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
fa30: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
fa40: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
fa50: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
fa60: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
fa70: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
fa80: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
fa90: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
faa0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
fab0: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
fac0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
fad0: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
fae0: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
faf0: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
fb00: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
fb10: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
fb20: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
fb30: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
fb40: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
fb50: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
fb60: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
fb70: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
fb80: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
fb90: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
fba0: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
fbb0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
fbc0: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
fbd0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
fbe0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
fbf0: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
fc00: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
fc10: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
fc20: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
fc30: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
fc40: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fc50: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
fc60: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
fc70: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fc80: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
fc90: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
fca0: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
fcb0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
fcc0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
fcd0: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
fce0: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
fcf0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
fd00: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
fd10: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fd20: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
fd30: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
fd40: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
fd50: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
fd60: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
fd70: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
fd80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
fd90: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
fda0: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
fdb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fdc0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
fdd0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
fde0: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
fdf0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
fe00: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
fe10: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
fe20: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
fe30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fe40: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
fe50: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
fe60: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fe70: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
fe80: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
fe90: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
fea0: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
feb0: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
fec0: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
fed0: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
fee0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
fef0: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
ff00: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
ff10: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
ff20: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
ff30: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
ff40: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
ff50: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
ff60: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
ff70: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
ff80: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
ff90: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
ffa0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
ffb0: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
ffc0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
ffd0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
ffe0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
fff0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
10000 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
10010 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
10020 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
10030 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
10040 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
10050 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10060 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
10070 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
10080 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
10090 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
100a0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
100b0 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
100c0 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
100d0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
100e0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
100f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
10100 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
10110 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10120 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
10130 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
10140 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
10150 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
10160 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
10170 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
10180 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
10190 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
101a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
101b0 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
101c0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
101d0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
101e0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
101f0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
10200 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
10210 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
10220 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
10230 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
10240 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
10250 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
10260 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
10270 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
10280 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
10290 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
102a0 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
102b0 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
102c0 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
102d0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
102e0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
102f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
10300 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
10310 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
10320 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10330 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
10340 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
10350 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
10360 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
10370 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10380 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
10390 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
103a0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
103b0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
103c0 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
103d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
103e0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
103f0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
10400 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
10410 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
10420 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
10430 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
10440 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
10450 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
10460 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
10470 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
10480 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10490 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
104a0 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
104b0 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
104c0 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
104d0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
104e0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
104f0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
10500 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
10510 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
10520 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
10530 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
10540 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
10550 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
10560 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
10570 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
10580 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
10590 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
105a0 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
105b0 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
105c0 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
105d0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
105e0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
105f0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
10600 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
10610 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
10620 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
10630 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
10640 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
10650 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
10660 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
10670 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
10680 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
10690 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
106a0 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
106b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
106c0 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
106d0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
106e0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
106f0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
10700 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
10710 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
10720 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
10730 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10740 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
10750 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
10760 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
10770 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
10780 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
10790 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
107a0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
107b0 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
107c0 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
107d0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
107e0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
107f0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
10800 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
10810 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10820 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
10830 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
10840 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
10850 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
10860 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
10870 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
10880 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
10890 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
108a0 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
108b0 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
108c0 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
108d0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
108e0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
108f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
10900 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
10910 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
10920 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
10930 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
10940 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10950 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
10960 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
10970 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
10980 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10990 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
109a0 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
109b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
109c0 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
109d0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
109e0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
109f0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
10a00 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
10a10 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
10a20 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
10a30 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
10a40 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
10a50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
10a60 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
10a70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
10a80 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10a90 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
10aa0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10ab0 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
10ac0 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
10ad0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10ae0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
10af0 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
10b00 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
10b10 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
10b20 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
10b30 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
10b40 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
10b50 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
10b60 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
10b70 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
10b80 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
10b90 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
10ba0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
10bb0 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
10bc0 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
10bd0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
10be0 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
10bf0 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
10c00 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
10c10 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
10c20 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c  **.** <b>The sql
10c30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10c40 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74  terface is not t
10c50 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61  hreadsafe. The a
10c60 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
10c70 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e  st ensure that n
10c80 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
10c90 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
10ca0 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
10cb0 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
10cc0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10cd0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e   is running.</b>
10ce0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10cf0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
10d00 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  rface.** may onl
10d10 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
10d20 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
10d30 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
10d40 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
10d50 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
10d60 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
10d70 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
10d80 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
10d90 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10da0 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
10db0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
10dc0 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
10dd0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
10de0 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
10df0 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
10e00 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
10e10 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
10e20 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
10e30 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
10e40 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
10e50 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
10e60 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
10e70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
10e80 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10e90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
10ea0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10eb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10ec0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
10ed0 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
10ee0 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
10ef0 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
10f00 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
10f10 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
10f20 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
10f30 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
10f40 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
10f50 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
10f60 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
10f70 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
10f80 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
10f90 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
10fa0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
10fb0 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
10fc0 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
10fd0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
10fe0 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
10ff0 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
11000 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
11010 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
11020 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
11030 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
11040 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
11050 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
11060 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e   int sqlite3_con
11070 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
11080 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11090 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
110a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
110b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
110c0 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
110d0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
110e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
110f0 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
11100 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
11110 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
11120 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
11130 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
11140 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
11150 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11160 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
11170 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
11180 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
11190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
111a0 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
111b0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
111c0 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ument)..**.** Th
111d0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
111e0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
111f0 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
11200 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   is the.** [SQLI
11210 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
11220 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72  ASIDE | configur
11230 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e  ation verb] - an
11240 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a   integer code .*
11250 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
11260 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20   what aspect of 
11270 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
11280 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
11290 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
112a0 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67  * Subsequent arg
112b0 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65  uments vary depe
112c0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e  nding on the con
112d0 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e  figuration verb.
112e0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .**.** ^Calls to
112f0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11300 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49  ig() return SQLI
11310 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
11320 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  y if.** the call
11330 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73   is considered s
11340 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51  uccessful..*/.SQ
11350 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
11360 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
11370 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
11380 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
11390 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
113a0 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
113b0 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
113c0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
113d0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
113e0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
113f0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
11400 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
11410 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11420 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
11430 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
11440 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
11450 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
11460 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
11470 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
11480 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
11490 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
114a0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
114b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
114c0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
114d0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
114e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
114f0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
11500 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11510 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
11520 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
11530 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
11540 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
11550 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
11560 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
11570 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11580 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
11590 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
115a0 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
115b0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
115c0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
115d0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
115e0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
115f0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
11600 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
11610 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
11620 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
11630 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
11640 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
11650 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
11660 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
11670 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
11680 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
11690 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
116a0 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
116b0 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
116c0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
116d0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
116e0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
116f0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
11700 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
11710 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11720 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
11730 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
11740 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
11750 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
11760 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
11770 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
11780 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
11790 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
117a0 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
117b0 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
117c0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
117d0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
117e0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
117f0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
11800 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
11810 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
11820 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
11830 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
11840 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
11850 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
11860 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
11870 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
11880 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
11890 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
118a0 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
118b0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
118c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
118d0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
118e0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
118f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
11900 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
11910 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
11920 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
11930 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
11940 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
11950 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
11960 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
11970 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
11980 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
11990 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
119a0 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
119b0 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
119c0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
119d0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
119e0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
119f0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
11a00 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
11a10 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
11a20 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
11a30 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
11a40 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
11a50 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
11a60 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
11a70 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
11a80 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
11a90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11aa0 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
11ab0 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
11ac0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
11ad0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
11ae0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
11af0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
11b00 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
11b10 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
11b20 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
11b30 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
11b40 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11b50 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
11b60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
11b70 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
11b80 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
11b90 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
11ba0 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
11bb0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
11bc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11bd0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
11be0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
11bf0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
11c00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11c10 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
11c20 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
11c30 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
11c40 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
11c50 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
11c60 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
11c70 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
11c80 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
11c90 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
11ca0 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
11cb0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
11cc0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
11cd0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
11ce0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
11cf0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
11d00 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
11d10 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
11d20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
11d30 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
11d40 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
11d50 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
11d60 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
11d70 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
11d80 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
11d90 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
11da0 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
11db0 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
11dc0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
11dd0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
11de0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
11df0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
11e00 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11e10 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
11e20 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
11e30 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
11e40 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
11e50 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
11e60 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
11e70 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
11e80 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
11e90 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
11ea0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11eb0 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
11ec0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11ed0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
11ee0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
11ef0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
11f00 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
11f10 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
11f20 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
11f30 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
11f40 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11f50 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
11f60 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
11f70 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
11f80 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
11f90 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
11fa0 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
11fb0 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
11fc0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
11fd0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
11fe0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
11ff0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
12000 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
12010 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
12020 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
12030 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
12040 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12050 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
12060 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
12070 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12080 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
12090 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
120a0 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
120b0 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
120c0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
120d0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
120e0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
120f0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
12100 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
12110 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
12120 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
12130 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
12140 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
12150 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
12160 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
12170 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
12180 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
12190 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
121a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
121b0 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
121c0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
121d0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
121e0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
121f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
12200 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
12210 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
12220 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
12230 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
12240 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
12250 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12260 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
12270 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
12280 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
12290 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
122a0 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
122b0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
122c0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
122d0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
122e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
122f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12300 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
12310 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
12320 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
12330 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
12340 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
12350 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
12360 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
12370 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
12380 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
12390 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
123a0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
123b0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
123c0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
123d0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
123e0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
123f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12400 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
12410 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
12420 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
12430 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
12440 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
12450 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12460 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
12470 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
12480 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
12490 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
124a0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
124b0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
124c0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
124d0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
124e0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
124f0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
12500 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
12510 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
12520 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
12530 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12540 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12550 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12560 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
12570 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
12580 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
12590 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
125a0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
125b0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
125c0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
125d0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
125e0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
125f0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
12600 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
12610 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
12620 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
12630 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
12640 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
12650 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12660 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12670 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12680 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12690 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
126a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
126b0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
126c0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
126d0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
126e0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
126f0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
12700 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
12710 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
12720 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12730 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
12740 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
12750 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
12760 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12770 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
12780 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12790 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
127a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
127b0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
127c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
127d0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
127e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
127f0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
12800 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
12810 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
12820 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
12830 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
12840 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
12850 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
12860 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
12870 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
12880 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12890 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
128a0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
128b0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
128c0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
128d0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
128e0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
128f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12900 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
12910 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
12920 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
12930 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
12940 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
12950 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
12960 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
12970 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
12980 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
12990 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
129a0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
129b0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
129c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
129d0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
129e0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
129f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12a00 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12a10 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12a20 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12a30 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
12a40 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
12a50 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
12a60 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
12a70 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
12a80 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
12a90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12aa0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12ab0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
12ac0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
12ad0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
12ae0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
12af0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12b00 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
12b10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12b20 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
12b30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12b40 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
12b50 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
12b60 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
12b70 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
12b80 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
12b90 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
12ba0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
12bb0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
12bc0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
12bd0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
12be0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
12bf0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
12c00 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
12c10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12c20 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
12c30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12c40 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
12c50 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
12c60 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
12c70 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
12c80 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
12c90 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12ca0 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
12cb0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
12cc0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
12cd0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
12ce0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12cf0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
12d00 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
12d10 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
12d20 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
12d30 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
12d40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12d50 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
12d60 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
12d70 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
12d80 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
12d90 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
12da0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
12db0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12dc0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
12dd0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
12de0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
12df0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12e00 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
12e10 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
12e20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
12e30 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
12e40 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
12e50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12e60 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12e70 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12e80 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12e90 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12ea0 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
12eb0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
12ec0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12ed0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12ee0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
12ef0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
12f00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
12f10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12f20 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
12f30 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12f40 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
12f50 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
12f60 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12f70 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12f80 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12f90 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
12fa0 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
12fb0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
12fc0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
12fd0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12fe0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
12ff0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
13000 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13010 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
13020 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
13030 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
13040 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
13050 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
13060 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
13070 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13080 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
13090 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
130a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
130b0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
130c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
130d0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
130e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
130f0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
13100 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
13110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13120 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
13130 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13140 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
13150 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13160 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13170 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13180 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13190 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
131a0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
131b0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
131c0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
131d0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
131e0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
131f0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
13200 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
13210 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
13220 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
13230 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
13240 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
13250 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
13260 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
13270 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
13280 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
13290 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
132a0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
132b0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
132c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
132d0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
132e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
132f0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
13300 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
13310 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13320 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
13330 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
13340 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
13350 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
13360 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
13370 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
13380 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
13390 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
133a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
133b0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
133c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
133d0 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
133e0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
133f0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
13400 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
13410 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
13420 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
13430 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
13440 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
13450 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
13460 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
13470 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
13480 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
13490 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
134a0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
134b0 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
134c0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
134d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
134e0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
134f0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
13500 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
13510 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
13520 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
13530 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
13540 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
13550 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
13560 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13570 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
13580 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
13590 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
135a0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
135b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
135c0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
135d0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
135e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
135f0 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  CH option specif
13600 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
13610 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  ory buffer.** th
13620 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
13630 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65  e for scratch me
13640 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61  mory.  ^(There a
13650 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
13660 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f  ts.** to SQLITE_
13670 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20  CONFIG_SCRATCH: 
13680 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
13690 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
136a0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
136b0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
136c0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
136d0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
136e0 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
136f0 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
13700 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
13710 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
13720 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
13730 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
13740 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ).)^.** The firs
13750 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
13760 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
13770 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
13780 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
13790 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
137a0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
137b0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f   ^SQLite will no
137c0 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20  t use more than 
137d0 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
137e0 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a  ers per thread..
137f0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
13800 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20  never request a 
13810 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
13820 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
13830 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
13840 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
13850 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  ze..** ^If SQLit
13860 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
13870 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
13880 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
13890 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
138a0 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
138b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
138c0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
138d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
138e0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
138f0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
13900 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68  eeded.<p>.** ^Wh
13910 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  en the applicati
13920 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20  on provides any 
13930 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63  amount of scratc
13940 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a  h memory using.*
13950 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
13960 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20  SCRATCH, SQLite 
13970 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61  avoids unnecessa
13980 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c  ry large.** [sql
13990 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70  ite3_malloc|heap
139a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a   allocations]..*
139b0 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20  * This can help 
139c0 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72  [Robson proof|pr
139d0 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  event memory all
139e0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  ocation failures
139f0 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a  ] due to heap.**
13a00 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69   fragmentation i
13a10 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62  n low-memory emb
13a20 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a  edded systems..*
13a30 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
13a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13a50 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
13a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13a70 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
13a80 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
13a90 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
13aa0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13ab0 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a   a memory pool.*
13ac0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
13ad0 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61  n use for the da
13ae0 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
13af0 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
13b00 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  lt page.** cache
13b10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13b20 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
13b30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
13b40 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e  is a no-op if an
13b50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
13b60 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
13b70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13b80 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
13b90 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
13ba0 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a  FIG_PCACHE2]..**
13bb0 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
13bc0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
13bd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13be0 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65  ECACHE: A pointe
13bf0 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61  r to.** 8-byte a
13c00 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70  ligned memory (p
13c10 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f  Mem), the size o
13c20 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63 68  f each page cach
13c30 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20  e line (sz),.** 
13c40 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
13c50 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e  f cache lines (N
13c60 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
13c70 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
13c80 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
13c90 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
13ca0 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
13cb0 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
13cc0 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 20   512 and 65536) 
13cd0 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20  plus some extra 
13ce0 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a  bytes for each.*
13cf0 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
13d00 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65  ^The number of e
13d10 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 65  xtra bytes neede
13d20 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68 65  d by the page he
13d30 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64  ader.** can be d
13d40 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
13d50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13d60 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a  CACHE_HDRSZ]..**
13d70 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
13d80 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
13d90 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
13da0 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61  ** for the sz pa
13db0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61  rameter to be la
13dc0 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73  rger than necess
13dd0 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a  ary.  The pMem.*
13de0 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
13df0 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
13e00 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f   pointer or a po
13e10 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
13e20 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c  te.** aligned bl
13e30 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66  ock of memory of
13e40 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
13e50 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a  ytes, otherwise.
13e60 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  ** subsequent be
13e70 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
13e80 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d  ned..** ^When pM
13e90 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  em is not NULL, 
13ea0 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69  SQLite will stri
13eb0 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65  ve to use the me
13ec0 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a  mory provided.**
13ed0 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 65   to satisfy page
13ee0 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61   cache needs, fa
13ef0 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73  lling back to [s
13f00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13f10 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61   if.** a page ca
13f20 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67  che line is larg
13f30 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73  er than sz bytes
13f40 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68   or if all of th
13f50 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a  e pMem buffer.**
13f60 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
13f70 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55  * ^If pMem is NU
13f80 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d  LL and N is non-
13f90 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20  zero, then each 
13fa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13fb0 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69  ion.** does an i
13fc0 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f  nitial bulk allo
13fd0 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20  cation for page 
13fe0 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  cache memory.** 
13ff0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
14000 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65  lloc()] sufficie
14010 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c  nt for N cache l
14020 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73  ines if N is pos
14030 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d  itive or.** of -
14040 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20  1024*N bytes if 
14050 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e  N is negative, .
14060 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
14070 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
14080 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
14090 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
140a0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69 6e  ovided by the in
140b0 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74  itial.** allocat
140c0 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ion, then SQLite
140d0 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
140e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61  3_malloc()] sepa
140f0 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a  rately for each.
14100 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61  ** additional ca
14110 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a  che line. </dd>.
14120 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14130 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74  ONFIG_HEAP]] <dt
14140 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
14150 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
14160 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14170 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
14180 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
14190 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
141a0 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65   .** that SQLite
141b0 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c   will use for al
141c0 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
141d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
141e0 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f  on needs.** beyo
141f0 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
14200 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  d for by [SQLITE
14210 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
14220 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
14230 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14240 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  ]..** ^The SQLIT
14250 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
14260 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
14270 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
14280 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
14290 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c  with either [SQL
142a0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
142b0 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45  S3] or [SQLITE_E
142c0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
142d0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  nd returns.** [S
142e0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
142f0 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73  invoked otherwis
14300 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65  e..** ^There are
14310 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
14320 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
14330 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d  G_HEAP:.** An 8-
14340 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
14350 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
14360 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
14370 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
14380 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
14390 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
143a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
143b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
143c0 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
143d0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
143e0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
143f0 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
14400 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
14410 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
14420 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
14430 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
14440 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
14450 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
14460 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
14470 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
14480 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
14490 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
144a0 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  r is not NULL th
144b0 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
144c0 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
144d0 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
144e0 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
144f0 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
14500 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
14510 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
14520 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
14530 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
14540 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
14550 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
14560 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
14570 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
14580 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
14590 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
145a0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
145b0 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
145c0 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
145d0 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
145e0 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
145f0 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
14600 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
14610 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
14620 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14630 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
14640 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
14650 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
14660 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14670 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69  ONFIG_MUTEX opti
14680 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14690 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
146a0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
146b0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
146c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
146d0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
146e0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
146f0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
14700 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ies alternative 
14710 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
14720 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
14730 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20  sed.** in place 
14740 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
14750 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
14760 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
14770 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
14780 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
14790 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
147a0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
147b0 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
147c0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
147d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
147e0 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
147f0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14800 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
14810 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14820 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14830 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14840 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14850 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14860 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14870 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14880 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
14890 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
148a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
148b0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
148c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
148d0 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
148e0 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
148f0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
14900 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
14910 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14920 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
14930 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14940 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
14950 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14960 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14970 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14980 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14990 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
149a0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
149b0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
149c0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
149d0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
149e0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
149f0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
14a00 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
14a10 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
14a20 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
14a30 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
14a40 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
14a50 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
14a60 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
14a70 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
14a80 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
14a90 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
14aa0 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
14ab0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
14ac0 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
14ad0 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
14ae0 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
14af0 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
14b00 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
14b10 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
14b20 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
14b30 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
14b40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14b50 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
14b60 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
14b70 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
14b80 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
14b90 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
14ba0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
14bb0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
14bc0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
14bd0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
14be0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14bf0 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
14c00 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14c10 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14c20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14c30 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
14c40 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14c50 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
14c60 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14c70 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
14c80 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
14c90 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
14ca0 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65  determine.** the
14cb0 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66   default size of
14cc0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
14cd0 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62  y on each [datab
14ce0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
14cf0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
14d00 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
14d10 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
14d20 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
14d30 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
14d40 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
14d50 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
14d60 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
14d70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14d80 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f  on.)^  ^(SQLITE_
14d90 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14da0 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e  .** sets the <i>
14db0 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b  default</i> look
14dc0 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20  aside size. The 
14dd0 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
14de0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f  _LOOKASIDE].** o
14df0 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65  ption to [sqlite
14e00 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
14e10 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
14e20 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
14e30 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
14e40 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
14e50 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
14e60 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14e80 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
14e90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14ea0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14eb0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14ec0 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  G_PCACHE2 option
14ed0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14ee0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
14ef0 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
14f00 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  to an [sqlite3_p
14f10 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
14f20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
14f30 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ject specifies.*
14f40 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  * the interface 
14f50 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
14f60 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14f70 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c  ation.)^.** ^SQL
14f80 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
14f90 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14fa0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14fb0 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a  ] object.</dd>.*
14fc0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14fd0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
14fe0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14ff0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
15000 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
15010 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15020 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f  GETPCACHE2 optio
15030 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15040 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
15050 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
15060 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  to an [sqlite3_p
15070 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
15080 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20  object.  SQLite 
15090 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65  copies of.** the
150a0 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61   current page ca
150b0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
150c0 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a  on into that obj
150d0 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ect.)^ </dd>.**.
150e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
150f0 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c  IG_LOG]] <dt>SQL
15100 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
15110 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20  dt>.** <dd> The 
15120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15130 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  G option is used
15140 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68   to configure th
15150 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62  e SQLite.** glob
15160 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a  al [error log]..
15170 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f  ** (^The SQLITE_
15180 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
15190 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
151a0 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
151b0 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
151c0 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
151d0 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
151e0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
151f0 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
15200 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
15210 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
15220 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
15230 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
15240 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
15250 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
15260 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
15270 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
15280 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
15290 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
152a0 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
152b0 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
152c0 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
152d0 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
152e0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
152f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15300 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
15310 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
15320 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
15330 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
15340 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
15350 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
15360 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
15370 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
15380 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
15390 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
153a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
153b0 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
153c0 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
153d0 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
153e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
153f0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
15400 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
15410 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
15420 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
15430 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
15440 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
15450 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
15460 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
15470 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
15480 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
15490 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
154a0 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
154b0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
154c0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
154d0 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
154e0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
154f0 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
15500 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
15510 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
15520 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
15530 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
15540 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
15550 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
15560 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
15570 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
15580 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
15590 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
155a0 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
155b0 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
155c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
155d0 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
155e0 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
155f0 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  d>^(The SQLITE_C
15600 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e  ONFIG_URI option
15610 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15620 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
15630 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d   int..** If non-
15640 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
15650 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
15660 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
15670 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
15680 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55   zero,.** then U
15690 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
156a0 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
156b0 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64  .)^ ^If URI hand
156c0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
156d0 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c  .** enabled, all
156e0 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65   filenames passe
156f0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
15700 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
15710 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  open_v2()],.** [
15720 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
15730 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65  ] or.** specifie
15740 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54  d as part of [AT
15750 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61  TACH] commands a
15760 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
15770 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65  s URIs, regardle
15780 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72  ss.** of whether
15790 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c   or not the [SQL
157a0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
157b0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
157c0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
157d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
157e0 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67  ned. ^If it is g
157f0 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
15800 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
15810 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
15820 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
15830 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
15840 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
15850 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
15860 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
15870 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64  s opened. ^(By d
15880 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
15890 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
158a0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
158b0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
158c0 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
158d0 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
158e0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
158f0 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
15900 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  defined.)^.**.**
15910 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15920 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
15930 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SCAN]] <dt>SQLIT
15940 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
15950 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20  G_INDEX_SCAN.** 
15960 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
15970 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
15980 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f  INDEX_SCAN optio
15990 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
159a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75   integer.** argu
159b0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e  ment which is in
159c0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
159d0 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20  oolean in order 
159e0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
159f0 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20  able.** the use 
15a00 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
15a10 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
15a20 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20  le scans in the 
15a30 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e  query optimizer.
15a40 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
15a50 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65   setting is dete
15a60 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
15a70 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43   [SQLITE_ALLOW_C
15a80 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
15a90 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  AN] compile-time
15aa0 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22   option, or is "
15ab0 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63  on".** if that c
15ac0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15ad0 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
15ae0 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f  * The ability to
15af0 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
15b00 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
15b10 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
15b20 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20  ble scans.** is 
15b30 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63  because some inc
15b40 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c  orrectly coded l
15b50 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f  egacy applicatio
15b60 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63  ns might malfunc
15b70 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  tion.** when the
15b80 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
15b90 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
15ba0 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
15bb0 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
15bc0 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
15bd0 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
15be0 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
15bf0 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
15c00 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
15c10 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
15c20 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
15c30 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
15c40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15c50 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
15c60 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
15c70 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15c80 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
15c90 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
15ca0 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
15cb0 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
15cc0 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
15cd0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
15ce0 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
15cf0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
15d00 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
15d10 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
15d20 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
15d30 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  -ops..** </dd>.*
15d40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15d50 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
15d60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15d70 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
15d80 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
15d90 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15da0 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
15db0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
15dc0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
15dd0 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63  SQLLOG] pre-proc
15de0 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
15df0 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
15e00 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
15e10 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
15e20 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
15e30 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
15e40 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
15e50 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
15e60 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
15e70 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
15e80 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
15e90 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
15ea0 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
15eb0 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
15ec0 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
15ed0 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
15ee0 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
15ef0 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
15f00 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
15f10 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
15f20 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
15f30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
15f40 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
15f50 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
15f60 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
15f70 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
15f80 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
15f90 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
15fa0 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
15fb0 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
15fc0 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
15fd0 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
15fe0 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
15ff0 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
16000 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
16010 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
16020 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
16030 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
16040 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
16050 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
16060 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
16070 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
16080 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
16090 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
160a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
160b0 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
160c0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
160d0 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
160e0 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
160f0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20    An example of 
16100 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f  using this.** co
16110 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16120 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69  on can be seen i
16130 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c  n the "test_sqll
16140 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c  og.c" source fil
16150 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f  e in.** the cano
16160 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75  nical SQLite sou
16170 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a  rce tree.</dd>.*
16180 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16190 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  NFIG_MMAP_SIZE]]
161a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
161b0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a  ONFIG_MMAP_SIZE.
161c0 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
161d0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
161e0 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74  takes two 64-bit
161f0 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65   integer (sqlite
16200 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a  3_int64) values.
16210 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20  ** that are the 
16220 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a  default mmap siz
16230 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66  e limit (the def
16240 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72  ault setting for
16250 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  .** [PRAGMA mmap
16260 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20  _size]) and the 
16270 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
16280 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e  mmap size limit.
16290 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
162a0 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20   setting can be 
162b0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61  overridden by ea
162c0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
162d0 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  ection using.** 
162e0 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47  either the [PRAG
162f0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f  MA mmap_size] co
16300 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69  mmand, or by usi
16310 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
16320 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
16330 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e  E] file control.
16340 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20    ^(The maximum 
16350 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
16360 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c  e.** will be sil
16370 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
16380 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20  if necessary so 
16390 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
163a0 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63   exceed the.** c
163b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69  ompile-time maxi
163c0 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65  mum mmap size se
163d0 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
163e0 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a  ITE_MAX_MMAP_SIZ
163f0 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
16400 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66  option.)^.** ^If
16410 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74   either argument
16420 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20   to this option 
16430 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
16440 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20  n that argument 
16450 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f  is.** changed to
16460 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   its compile-tim
16470 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  e default..**.**
16480 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16490 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d  _WIN32_HEAPSIZE]
164a0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
164b0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
164c0 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PSIZE.** <dd>^Th
164d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
164e0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f  WIN32_HEAPSIZE o
164f0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
16500 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
16510 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
16520 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74   for Windows wit
16530 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49  h the [SQLITE_WI
16540 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d  N32_MALLOC] pre-
16550 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a  processor macro.
16560 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c  ** defined. ^SQL
16570 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16580 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20  _HEAPSIZE takes 
16590 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 32-bit unsigne
165a0 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a  d integer value.
165b0 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65  ** that specifie
165c0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  s the maximum si
165d0 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65  ze of the create
165e0 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  d heap..**.** [[
165f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16600 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20  ACHE_HDRSZ]].** 
16610 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16620 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a  G_PCACHE_HDRSZ.*
16630 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
16640 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
16650 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  HDRSZ option tak
16660 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
16670 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
16680 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16690 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72  n integer and wr
166a0 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69  ites into that i
166b0 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65  nteger the numbe
166c0 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79  r of extra.** by
166d0 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71  tes per page req
166e0 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70  uired for each p
166f0 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43  age in [SQLITE_C
16700 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
16710 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20  ..** The amount 
16720 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72  of extra space r
16730 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e  equired can chan
16740 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ge depending on 
16750 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a  the compiler,.**
16760 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d   target platform
16770 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  , and SQLite ver
16780 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  sion..**.** [[SQ
16790 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
167a0 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
167b0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a  E_CONFIG_PMASZ.*
167c0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
167d0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f  E_CONFIG_PMASZ o
167e0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
167f0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
16800 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e  hich.** is an un
16810 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
16820 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e  nd sets the "Min
16830 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66  imum PMA Size" f
16840 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65  or the multithre
16850 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74  aded.** sorter t
16860 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20  o that integer. 
16870 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e   The default min
16880 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73  imum PMA Size is
16890 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
168a0 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d  SQLITE_SORTER_PM
168b0 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ASZ] compile-tim
168c0 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74  e option.  New t
168d0 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63  hreads are launc
168e0 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77  hed.** to help w
168f0 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69  ith sort operati
16900 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68  ons when multith
16910 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a  readed sorting.*
16920 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73  * is enabled (us
16930 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ing the [PRAGMA 
16940 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64  threads] command
16950 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74  ) and the amount
16960 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74   of content.** t
16970 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65  o be sorted exce
16980 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a  eds the page siz
16990 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69  e times the mini
169a0 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50  mum of the.** [P
169b0 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65  RAGMA cache_size
169c0 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68  ] setting and th
169d0 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  is value..**.** 
169e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
169f0 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d  STMTJRNL_SPILL]]
16a00 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16a10 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
16a20 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  PILL.** <dd>^The
16a30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16a40 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70  TMTJRNL_SPILL op
16a50 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16a60 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
16a70 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74  ich.** becomes t
16a80 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f  he [statement jo
16a90 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d  urnal] spill-to-
16aa0 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20  disk threshold. 
16ab0 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20   .** [Statement 
16ac0 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65  journals] are he
16ad0 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74  ld in memory unt
16ae0 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69  il their size (i
16af0 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65  n bytes).** exce
16b00 65 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f  eds this thresho
16b10 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69  ld, at which poi
16b20 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74  nt they are writ
16b30 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20  ten to disk..** 
16b40 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68  Or if the thresh
16b50 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65  old is -1, state
16b60 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72  ment journals ar
16b70 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a  e always held.**
16b80 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20   exclusively in 
16b90 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65  memory..** Since
16ba0 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20   many statement 
16bb0 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62  journals never b
16bc0 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74  ecome large, set
16bd0 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a  ting the spill.*
16be0 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61  * threshold to a
16bf0 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36   value such as 6
16c00 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79  4KiB can greatly
16c10 20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75   reduce the amou
16c20 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71  nt of.** I/O req
16c30 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74  uired to support
16c40 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62   statement rollb
16c50 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  ack..** The defa
16c60 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
16c70 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f  is setting is co
16c80 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a  ntrolled by the.
16c90 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a  ** [SQLITE_STMTJ
16ca0 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69  RNL_SPILL] compi
16cb0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
16cc0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
16cd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16ce0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
16cf0 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
16d00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d10 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
16d20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
16d30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16d40 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
16d50 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
16d60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16d70 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
16d80 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
16d90 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
16da0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16db0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
16dc0 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
16dd0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
16de0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16df0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
16e00 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
16e10 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
16e20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
16e30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
16e40 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
16e50 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
16e60 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
16e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
16e80 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
16e90 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
16ea0 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
16eb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16ec0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
16ed0 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
16ee0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16ef0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
16f00 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
16f10 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16f20 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16f30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16f40 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
16f50 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
16f60 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
16f70 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
16f80 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
16f90 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
16fa0 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
16fb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16fc0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
16fd0 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
16fe0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16ff0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
17000 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
17010 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
17020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
17030 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
17040 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
17050 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
17060 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
17070 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
17080 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17090 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
170a0 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
170b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
170c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
170d0 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
170e0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
170f0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
17100 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17110 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
17120 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
17130 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
17140 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17150 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
17160 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
17170 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
17180 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
17190 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
171a0 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
171b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
171c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
171d0 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
171e0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
171f0 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
17200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17210 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17220 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
17230 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
17240 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17250 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20  G_PCACHE_HDRSZ  
17260 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74        24  /* int
17270 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65   *psz */.#define
17280 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17290 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20  MASZ            
172a0 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e     25  /* unsign
172b0 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a  ed int szPma */.
172c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
172d0 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
172e0 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a  PILL      26  /*
172f0 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f   int nByte */../
17300 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
17310 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
17320 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
17330 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
17340 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
17350 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
17360 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
17370 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
17380 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
17390 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
173a0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
173b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
173c0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
173d0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
173e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
173f0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
17400 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
17410 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
17420 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
17430 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
17440 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
17450 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
17460 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
17470 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
17480 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
17490 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
174a0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
174b0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
174c0 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
174d0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
174e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
174f0 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
17500 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
17510 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
17520 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
17530 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
17540 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
17550 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
17560 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
17570 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
17580 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
17590 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
175a0 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
175b0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
175c0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
175d0 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
175e0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
175f0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
17600 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
17610 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
17620 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
17630 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
17640 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
17650 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17660 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
17670 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
17680 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
17690 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
176a0 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
176b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
176c0 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
176d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
176e0 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
176f0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
17700 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
17710 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
17720 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
17730 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
17740 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
17750 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
17760 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
17770 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
17780 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
17790 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
177a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
177b0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
177c0 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
177d0 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
177e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
177f0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
17800 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
17810 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
17820 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
17830 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
17840 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
17850 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
17860 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
17870 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
17880 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
17890 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
178a0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
178b0 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
178c0 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
178d0 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
178e0 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
178f0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
17900 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
17910 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
17920 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
17930 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
17940 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17950 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
17960 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
17970 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
17980 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
17990 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
179a0 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
179b0 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
179c0 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
179d0 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
179e0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
179f0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
17a00 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
17a10 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
17a20 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
17a30 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
17a40 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
17a50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
17a60 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
17a70 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
17a80 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
17a90 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
17aa0 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
17ab0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
17ac0 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
17ad0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17ae0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
17af0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
17b00 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
17b10 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
17b20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
17b30 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
17b40 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
17b50 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
17b60 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
17b70 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17b80 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
17b90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
17ba0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
17bb0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
17bc0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
17bd0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17be0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
17bf0 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
17c00 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
17c10 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
17c20 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
17c30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17c40 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17c50 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17c60 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
17c70 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17c80 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
17c90 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
17ca0 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
17cb0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
17cc0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17cd0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
17ce0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
17cf0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
17d00 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
17d10 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
17d20 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
17d30 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
17d40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
17d50 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
17d60 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
17d70 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
17d80 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
17d90 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
17da0 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
17db0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
17dc0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
17dd0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
17de0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
17df0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
17e00 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
17e10 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
17e20 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
17e30 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
17e40 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
17e50 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
17e60 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
17e70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17e80 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
17e90 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
17ea0 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
17eb0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
17ec0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
17ed0 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
17ee0 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
17ef0 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
17f00 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
17f10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17f20 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
17f30 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
17f40 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
17f50 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
17f60 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
17f70 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
17f80 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17f90 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
17fa0 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a  TOKENIZER</dt>.*
17fb0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17fc0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
17fd0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
17fe0 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e   the two-argumen
17ff0 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  t.** version of 
18000 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69  the [fts3_tokeni
18010 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  zer()] function 
18020 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66  which is part of
18030 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66   the.** [FTS3] f
18040 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20  ull-text search 
18050 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e  engine extension
18060 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
18070 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
18080 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
18090 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
180a0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
180b0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
180c0 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f   disable fts3_to
180d0 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20  kenizer() or.** 
180e0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
180f0 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  le fts3_tokenize
18100 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20  r() or negative 
18110 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
18120 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ting.** unchange
18130 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
18140 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18150 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
18160 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
18170 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
18180 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
18190 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74  e whether fts3_t
181a0 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61  okenizer is disa
181b0 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
181c0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
181d0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
181e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
181f0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
18200 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
18210 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65   case the new se
18220 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
18230 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
18240 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18250 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18260 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
18270 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  N</dt>.** <dd> ^
18280 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
18290 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
182a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71   disable the [sq
182b0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
182c0 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  sion()].** inter
182d0 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74  face independent
182e0 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f  ly of the [load_
182f0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c  extension()] SQL
18300 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
18310 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  e [sqlite3_enabl
18320 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
18330 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20  ()] API enables 
18340 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68  or disables both
18350 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73   the.** C-API [s
18360 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18370 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65  nsion()] and the
18380 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c   SQL function [l
18390 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
183a0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
183b0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
183c0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
183d0 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74  * When the first
183e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
183f0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31  s interface is 1
18400 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20  , then only the 
18410 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62  C-API is.** enab
18420 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  led and the SQL 
18430 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73  function remains
18440 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74   disabled.  If t
18450 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18460 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74  t to.** this int
18470 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65  erface is 0, the
18480 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49  n both the C-API
18490 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
184a0 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c  ction are disabl
184b0 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  ed..** If the fi
184c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
184d0 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e  -1, then no chan
184e0 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20  ges are made to 
184f0 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20  state of either 
18500 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20  the.** C-API or 
18510 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
18520 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
18530 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
18540 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18550 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18560 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18570 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18580 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65   whether [sqlite
18590 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
185a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
185b0 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20   is disabled or 
185c0 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e  enabled followin
185d0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
185e0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
185f0 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e  er may.** be a N
18600 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20  ULL pointer, in 
18610 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
18620 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  ew setting is no
18630 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
18640 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
18650 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18660 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f  FIG_MAINDBNAME</
18670 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
18680 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
18690 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e   to change the n
186a0 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e  ame of the "main
186b0 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63  " database.** sc
186c0 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65  hema.  ^The sole
186d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
186e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73  ointer to a cons
186f0 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67  tant UTF8 string
18700 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  .** which will b
18710 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63  ecome the new sc
18720 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61  hema name in pla
18730 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e  ce of "main".  ^
18740 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e  SQLite.** does n
18750 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ot make a copy o
18760 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73  f the new main s
18770 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e  chema name strin
18780 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63  g, so the applic
18790 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e  ation.** must en
187a0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72  sure that the ar
187b0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e  gument passed in
187c0 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47  to this DBCONFIG
187d0 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61   option is uncha
187e0 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66  nged.** until af
187f0 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65  ter the database
18800 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
18810 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  es..** </dd>.**.
18820 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
18830 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f  CONFIG_NO_CKPT_O
18840 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  N_CLOSE</dt>.** 
18850 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68  <dd> Usually, wh
18860 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e  en a database in
18870 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f   wal mode is clo
18880 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20  sed or detached 
18890 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62  from a .** datab
188a0 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69  ase handle, SQLi
188b0 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69  te checks if thi
188c0 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74  s will mean that
188d0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e   there are now n
188e0 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  o .** connection
188f0 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20  s at all to the 
18900 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c  database. If so,
18910 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63   it performs a c
18920 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70  heckpoint .** op
18930 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63  eration before c
18940 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65  losing the conne
18950 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69  ction. This opti
18960 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  on may be used t
18970 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68  o.** override th
18980 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68  is behaviour. Th
18990 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
189a0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73  r passed to this
189b0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73   operation.** is
189c0 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f   an integer - no
189d0 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c  n-zero to disabl
189e0 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  e checkpoints-on
189f0 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20  -close, or zero 
18a00 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29  (the.** default)
18a10 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e   to enable them.
18a20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18a30 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
18a40 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
18a50 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69  .** into which i
18a60 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
18a70 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
18a80 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73  ther checkpoints
18a90 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76  -on-close.** hav
18aa0 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20  e been disabled 
18ab0 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20  - 0 if they are 
18ac0 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20  not disabled, 1 
18ad0 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20  if they are..** 
18ae0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18af0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18b00 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e  ENABLE_QPSG</dt>
18b10 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
18b20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18b30 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e  ABLE_QPSG option
18b40 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65   activates or de
18b50 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65  activates.** the
18b60 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20   [query planner 
18b70 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e  stability guaran
18b80 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68  tee] (QPSG).  Wh
18b90 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 61  en the QPSG is a
18ba0 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67  ctive,.** a sing
18bb0 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 61  le SQL query sta
18bc0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61  tement will alwa
18bd0 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  ys use the same 
18be0 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64  algorithm regard
18bf0 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65  less.** of value
18c00 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  s of [bound para
18c10 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51  meters].)^ The Q
18c20 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d  PSG disables som
18c30 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61  e query optimiza
18c40 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f  tions.** that lo
18c50 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 73  ok at the values
18c60 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65   of bound parame
18c70 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20  ters, which can 
18c80 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65  make some querie
18c90 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75  s.** slower.  Bu
18ca0 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20 74  t the QPSG has t
18cb0 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20  he advantage of 
18cc0 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c 65  more predictable
18cd0 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68   behavior.  With
18ce0 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 74  .** the QPSG act
18cf0 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ive, SQLite will
18d00 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20   always use the 
18d10 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20  same query plan 
18d20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a  in the field as.
18d30 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 69  ** was used duri
18d40 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68  ng testing in th
18d50 65 20 6c 61 62 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  e lab..** </dd>.
18d60 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
18d70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18d80 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d  CONFIG_MAINDBNAM
18d90 45 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30  E            100
18da0 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a  0 /* const char*
18db0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18dc0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
18dd0 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20 20  ASIDE           
18de0 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20    1001 /* void* 
18df0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
18e00 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18e10 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
18e20 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a           1002 /*
18e30 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18e40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18e50 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
18e60 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33 20  GER        1003 
18e70 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
18e80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18e90 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
18ea0 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30  S3_TOKENIZER 100
18eb0 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  4 /* int int* */
18ec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18ed0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18ee0 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31  LOAD_EXTENSION 1
18ef0 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  005 /* int int* 
18f00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18f10 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b  E_DBCONFIG_NO_CK
18f20 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20  PT_ON_CLOSE     
18f30 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74   1006 /* int int
18f40 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18f50 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18f60 42 4c 45 5f 51 50 53 47 20 20 20 20 20 20 20 20  BLE_QPSG        
18f70 20 20 20 31 30 30 37 20 2f 2a 20 69 6e 74 20 69     1007 /* int i
18f80 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
18f90 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
18fa0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
18fb0 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
18fc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
18fd0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
18fe0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
18ff0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
19000 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
19010 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
19020 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
19030 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
19040 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
19050 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
19060 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
19070 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
19080 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
19090 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
190a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
190b0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
190c0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
190d0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
190e0 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
190f0 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
19100 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54  ert Rowid.** MET
19110 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
19120 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
19130 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61  n most SQLite ta
19140 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72  bles (except for
19150 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
19160 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20   tables).** has 
19170 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
19180 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
19190 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
191a0 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
191b0 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
191c0 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
191d0 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
191e0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
191f0 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
19200 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
19210 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
19220 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
19230 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
19240 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
19250 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
19260 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
19270 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
19280 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
19290 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
192a0 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
192b0 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
192c0 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
192d0 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  e sqlite3_last_i
192e0 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69  nsert_rowid(D) i
192f0 6e 74 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79  nterface usually
19300 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
19310 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  wid] of.** the m
19320 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
19330 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
19340 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c  nto a rowid tabl
19350 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61  e or [virtual ta
19360 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62  ble].** on datab
19370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
19380 2e 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20  . ^Inserts into 
19390 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
193a0 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a  tables are not.*
193b0 2a 20 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20  * recorded. ^If 
193c0 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
193d0 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77  NSERT]s into row
193e0 69 64 20 74 61 62 6c 65 73 20 68 61 76 65 20 65  id tables have e
193f0 76 65 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a  ver occurred .**
19400 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
19410 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74   connection D, t
19420 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  hen sqlite3_last
19430 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
19440 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72   returns .** zer
19450 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c  o..**.** As well
19460 20 61 73 20 62 65 69 6e 67 20 73 65 74 20 61 75   as being set au
19470 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72  tomatically as r
19480 6f 77 73 20 61 72 65 20 69 6e 73 65 72 74 65 64  ows are inserted
19490 20 69 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a   into database.*
194a0 2a 20 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61  * tables, the va
194b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
194c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  this function ma
194d0 79 20 62 65 20 73 65 74 20 65 78 70 6c 69 63 69  y be set explici
194e0 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  tly by.** [sqlit
194f0 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
19500 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a  rt_rowid()].**.*
19510 2a 20 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74  * Some virtual t
19520 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
19530 69 6f 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20  ions may INSERT 
19540 72 6f 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  rows into rowid 
19550 74 61 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72  tables as.** par
19560 74 20 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20  t of committing 
19570 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  a transaction (e
19580 2e 67 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74  .g. to flush dat
19590 61 20 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e  a accumulated in
195a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69   memory.** to di
195b0 73 6b 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73  sk). In this cas
195c0 65 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  e subsequent cal
195d0 6c 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ls to this funct
195e0 69 6f 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72  ion return the r
195f0 6f 77 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74  owid.** associat
19600 65 64 20 77 69 74 68 20 74 68 65 73 65 20 69 6e  ed with these in
19610 74 65 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70  ternal INSERT op
19620 65 72 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20  erations, which 
19630 6c 65 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69  leads to .** uni
19640 6e 74 75 69 74 69 76 65 20 72 65 73 75 6c 74 73  ntuitive results
19650 2e 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  . Virtual table 
19660 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
19670 74 68 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f  that do write to
19680 20 72 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73   rowid.** tables
19690 20 69 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e   in this way can
196a0 20 61 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62   avoid this prob
196b0 6c 65 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67  lem by restoring
196c0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a   the original .*
196d0 2a 20 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73  * rowid value us
196e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  ing [sqlite3_set
196f0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19700 69 64 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74  id()] before ret
19710 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72  urning .** contr
19720 6f 6c 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a  ol to the user..
19730 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
19740 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
19750 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 74  thin a trigger t
19760 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
19770 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e   will .** return
19780 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
19790 74 68 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77  the inserted row
197a0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
197b0 74 72 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72  trigger is .** r
197c0 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65  unning. Once the
197d0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
197e0 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
197f0 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
19800 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
19810 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
19820 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
19830 74 72 69 67 67 65 72 20 77 61 73 20 66 69 72 65  trigger was fire
19840 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  d.)^.**.** ^An [
19850 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
19860 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
19870 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
19880 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
19890 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
198a0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
198b0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
198c0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
198d0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
198e0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
198f0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
19900 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
19910 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
19920 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
19930 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
19940 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
19950 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
19960 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
19970 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
19980 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
19990 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
199a0 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
199b0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
199c0 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
199d0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
199e0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
199f0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
19a00 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
19a10 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
19a20 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
19a30 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
19a40 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
19a50 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
19a60 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
19a70 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
19a80 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
19a90 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
19aa0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
19ab0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
19ac0 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
19ad0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
19ae0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
19af0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
19b00 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
19b10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
19b20 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
19b30 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
19b40 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
19b50 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
19b60 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
19b70 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
19b80 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
19b90 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
19ba0 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
19bb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
19bc0 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
19bd0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19be0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
19bf0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
19c00 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
19c10 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
19c20 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
19c30 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19c40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
19c50 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19c60 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
19c70 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
19c80 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
19c90 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
19ca0 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
19cb0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
19cc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
19cd0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
19ce0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19cf0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
19d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19d10 53 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73  Set the Last Ins
19d20 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e  ert Rowid value.
19d30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19d40 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te3.**.** The sq
19d50 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
19d60 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52  nsert_rowid(D, R
19d70 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20  ) method allows 
19d80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19d90 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61  to.** set the va
19da0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19db0 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
19dc0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19dd0 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69  d(D) to R .** wi
19de0 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20  thout inserting 
19df0 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64  a row into the d
19e00 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 53 51 4c 49  atabase..*/.SQLI
19e10 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
19e20 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
19e30 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
19e40 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  3*,sqlite3_int64
19e50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19e60 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
19e70 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
19e80 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
19e90 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
19ea0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
19eb0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
19ec0 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
19ed0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
19ee0 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
19ef0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
19f00 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
19f10 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
19f20 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
19f30 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
19f40 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
19f50 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
19f60 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
19f70 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
19f80 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
19f90 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
19fa0 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
19fb0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
19fc0 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
19fd0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
19fe0 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
19ff0 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
1a000 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1a010 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
1a020 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
1a030 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
1a040 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
1a050 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
1a060 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
1a070 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
1a080 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
1a090 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
1a0a0 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
1a0b0 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
1a0c0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1a0d0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1a0e0 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
1a0f0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1a100 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
1a110 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
1a120 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
1a130 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
1a140 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
1a150 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
1a160 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
1a170 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
1a180 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1a190 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
1a1a0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
1a1b0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
1a1c0 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
1a1d0 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
1a1e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
1a1f0 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
1a200 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
1a210 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
1a220 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
1a230 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
1a240 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
1a250 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
1a260 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
1a270 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
1a280 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1a290 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
1a2a0 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
1a2b0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1a2c0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
1a2d0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
1a2e0 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
1a2f0 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
1a300 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
1a310 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
1a320 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
1a330 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a340 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
1a350 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1a360 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
1a370 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
1a380 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
1a390 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
1a3a0 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
1a3b0 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
1a3c0 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
1a3d0 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
1a3e0 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1a3f0 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
1a400 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
1a410 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
1a420 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
1a430 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1a440 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a450 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
1a460 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
1a470 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
1a480 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
1a490 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
1a4a0 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
1a4b0 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
1a4c0 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
1a4d0 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
1a4e0 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1a4f0 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
1a500 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
1a510 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
1a520 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
1a530 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
1a540 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
1a550 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
1a560 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
1a570 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
1a580 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
1a590 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
1a5a0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1a5b0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1a5c0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1a5d0 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
1a5e0 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
1a5f0 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
1a600 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
1a610 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
1a620 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
1a630 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
1a640 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
1a650 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1a660 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
1a670 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
1a680 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
1a690 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
1a6a0 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
1a6b0 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
1a6c0 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
1a6d0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1a6e0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
1a6f0 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
1a700 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
1a710 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
1a720 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
1a730 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1a740 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1a750 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1a760 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1a770 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1a780 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1a790 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1a7a0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1a7b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a7c0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1a7d0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1a7e0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1a7f0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a800 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
1a810 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
1a820 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
1a830 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1a840 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
1a850 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1a860 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
1a870 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1a880 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1a890 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1a8a0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1a8b0 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
1a8c0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a8d0 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
1a8e0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1a8f0 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
1a900 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
1a910 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
1a920 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
1a930 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
1a940 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
1a950 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
1a960 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
1a970 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
1a980 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
1a990 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
1a9a0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1a9b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1a9c0 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
1a9d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a9e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
1a9f0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
1aa00 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
1aa10 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
1aa20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1aa30 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
1aa40 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
1aa50 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
1aa60 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
1aa70 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
1aa80 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
1aa90 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
1aaa0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
1aab0 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
1aac0 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
1aad0 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
1aae0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
1aaf0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
1ab00 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1ab10 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
1ab20 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
1ab30 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
1ab40 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
1ab50 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1ab60 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1ab70 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1ab80 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1ab90 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1aba0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1abb0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1abc0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1abd0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1abe0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
1abf0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
1ac00 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1ac10 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53  meaningful..*/.S
1ac20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1ac30 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1ac40 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1ac50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ac60 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
1ac70 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
1ac80 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1ac90 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
1aca0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
1acb0 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
1acc0 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
1acd0 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
1ace0 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
1acf0 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
1ad00 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
1ad10 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
1ad20 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
1ad30 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
1ad40 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
1ad50 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
1ad60 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
1ad70 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
1ad80 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
1ad90 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
1ada0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
1adb0 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
1adc0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
1add0 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
1ade0 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
1adf0 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
1ae00 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
1ae10 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
1ae20 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
1ae30 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
1ae40 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
1ae50 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1ae60 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
1ae70 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
1ae80 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
1ae90 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
1aea0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1aeb0 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
1aec0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
1aed0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
1aee0 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
1aef0 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
1af00 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
1af10 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
1af20 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
1af30 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
1af40 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
1af50 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
1af60 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
1af70 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
1af80 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
1af90 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
1afa0 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
1afb0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
1afc0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
1afd0 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
1afe0 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
1aff0 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
1b000 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
1b010 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
1b020 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
1b030 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
1b040 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
1b050 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
1b060 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
1b070 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
1b080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b090 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
1b0a0 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
1b0b0 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
1b0c0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
1b0d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b0e0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
1b0f0 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
1b100 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
1b110 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1b120 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1b130 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1b140 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1b150 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
1b160 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
1b170 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
1b180 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
1b190 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
1b1a0 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
1b1b0 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
1b1c0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1b1d0 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
1b1e0 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
1b1f0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1b200 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1b210 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1b220 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
1b230 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
1b240 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
1b250 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1b260 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
1b270 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
1b280 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
1b290 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
1b2a0 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
1b2b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1b2c0 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
1b2d0 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
1b2e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1b2f0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1b300 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1b310 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1b320 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
1b330 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1b340 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1b350 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1b360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b370 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1b380 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1b390 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1b3a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1b3b0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1b3c0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1b3d0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1b3e0 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1b3f0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1b400 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1b410 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1b420 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1b430 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1b440 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1b450 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1b460 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1b470 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1b480 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1b490 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1b4a0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1b4b0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1b4c0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1b4d0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1b4e0 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1b4f0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1b500 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1b510 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1b520 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1b530 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1b540 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1b550 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1b560 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1b570 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1b580 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1b590 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1b5a0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1b5b0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1b5c0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1b5d0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1b5e0 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1b5f0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1b600 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1b610 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1b620 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1b630 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1b640 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1b650 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1b660 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1b670 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1b680 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1b690 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1b6a0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1b6b0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1b6c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1b6d0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1b6e0 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1b6f0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1b700 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1b710 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1b720 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1b730 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1b740 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b750 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1b760 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1b770 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1b780 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1b790 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1b7a0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1b7b0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1b7c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1b7d0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1b7e0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1b7f0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1b800 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1b810 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1b820 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1b830 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1b840 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1b850 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1b860 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1b870 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1b880 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1b890 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1b8a0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1b8b0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1b8c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1b8d0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1b8e0 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1b8f0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1b900 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1b910 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1b920 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1b930 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1b940 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1b950 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1b960 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1b970 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1b980 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1b990 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1b9a0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
1b9b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1b9c0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1b9d0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51  t char *sql);.SQ
1b9e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1b9f0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1ba00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1ba10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ba20 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1ba30 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1ba40 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1ba50 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
1ba60 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
1ba70 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
1ba80 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
1ba90 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1baa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
1bab0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
1bac0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
1bad0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1bae0 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
1baf0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1bb00 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
1bb10 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
1bb20 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1bb30 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
1bb40 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
1bb50 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
1bb60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bb70 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
1bb80 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
1bb90 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
1bba0 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
1bbb0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1bbc0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
1bbd0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
1bbe0 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
1bbf0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1bc00 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
1bc10 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
1bc20 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
1bc30 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1bc40 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
1bc50 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
1bc60 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1bc70 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1bc80 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1bc90 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1bca0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1bcb0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1bcc0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1bcd0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1bce0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1bcf0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1bd00 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1bd10 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1bd20 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1bd30 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1bd40 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1bd50 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1bd60 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1bd70 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1bd80 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1bd90 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1bda0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1bdb0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1bdc0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1bdd0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1bde0 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1bdf0 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1be00 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1be10 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1be20 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1be30 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1be40 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1be50 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1be60 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1be70 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1be80 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1be90 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1bea0 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1beb0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1bec0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1bed0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1bee0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1bef0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1bf00 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1bf10 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1bf20 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1bf30 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1bf40 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1bf50 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1bf60 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1bf70 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1bf80 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1bf90 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1bfa0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1bfb0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1bfc0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1bfd0 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1bfe0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1bff0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1c000 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1c010 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1c020 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1c030 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1c040 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1c050 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1c060 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1c070 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1c080 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1c090 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1c0a0 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1c0b0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1c0c0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1c0d0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1c0e0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1c0f0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1c100 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1c110 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1c120 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1c130 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1c140 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1c150 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1c160 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1c170 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1c180 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1c190 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1c1a0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1c1b0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1c1c0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1c1d0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1c1e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1c1f0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1c200 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1c210 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1c220 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1c230 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1c240 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1c250 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1c260 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1c270 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1c280 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1c290 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1c2a0 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1c2b0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1c2c0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1c2d0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1c2e0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1c2f0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1c300 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1c310 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1c320 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1c330 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1c340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1c350 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1c360 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1c370 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1c380 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1c390 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1c3a0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1c3b0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1c3c0 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1c3d0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1c3e0 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1c3f0 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1c400 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1c410 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1c420 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1c430 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1c440 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1c450 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1c460 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1c470 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1c480 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c490 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1c4a0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1c4b0 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1c4c0 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1c4d0 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1c4e0 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1c4f0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1c500 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1c510 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1c520 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1c530 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1c540 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1c550 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1c560 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1c570 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1c580 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1c590 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
1c5a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
1c5b0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1c5c0 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1c5d0 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1c5e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c5f0 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1c600 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1c610 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1c620 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1c630 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1c640 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1c650 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1c660 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1c670 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1c680 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1c690 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1c6a0 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1c6b0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1c6c0 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1c6d0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1c6e0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1c6f0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1c700 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1c710 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1c720 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1c730 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1c740 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1c750 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1c760 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c770 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1c780 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1c790 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1c7a0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1c7b0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1c7c0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1c7d0 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1c7e0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1c7f0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1c800 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1c810 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1c820 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1c830 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1c840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1c850 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1c860 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1c870 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1c880 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1c890 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1c8a0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1c8b0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1c8c0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1c8d0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1c8e0 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1c8f0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1c900 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1c910 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1c920 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1c930 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1c940 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1c950 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1c960 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1c970 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1c980 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1c990 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1c9a0 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te3.**.** This i
1c9b0 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1c9c0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1c9d0 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1c9e0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1c9f0 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1ca00 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1ca10 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1ca20 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1ca30 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1ca40 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1ca50 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1ca60 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1ca70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1ca80 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1ca90 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1caa0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1cab0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1cac0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1cad0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1cae0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1caf0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1cb00 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1cb10 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1cb20 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1cb30 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1cb40 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1cb50 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1cb60 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1cb70 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1cb80 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1cb90 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1cba0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1cbb0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1cbc0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1cbd0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1cbe0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1cbf0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1cc00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1cc10 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1cc20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1cc30 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1cc40 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1cc50 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1cc60 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1cc70 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1cc80 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1cc90 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1cca0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1ccb0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1ccc0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1ccd0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1cce0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1ccf0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1cd00 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1cd10 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1cd20 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1cd30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1cd40 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1cd50 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1cd60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1cd70 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1cd80 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1cd90 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1cda0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1cdb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1cdc0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1cdd0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1cde0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1cdf0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1ce00 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1ce10 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1ce20 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1ce30 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1ce40 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1ce50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1ce60 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1ce70 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1ce80 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1ce90 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1cea0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1ceb0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1cec0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1ced0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1cee0 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1cef0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cf00 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1cf10 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1cf20 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1cf30 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1cf40 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1cf50 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1cf60 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1cf70 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1cf80 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1cf90 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1cfa0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1cfb0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1cfc0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1cfd0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1cfe0 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1cff0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1d000 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1d010 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1d020 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1d030 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1d040 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1d050 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d060 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1d070 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d080 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1d090 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1d0a0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1d0b0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1d0c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1d0d0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1d0e0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1d0f0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1d100 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1d110 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1d120 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d130 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1d140 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d150 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1d160 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1d170 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1d180 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1d190 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1d1a0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1d1b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1d1c0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1d1d0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1d1e0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1d1f0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1d200 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1d210 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1d220 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1d230 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1d240 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1d250 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1d260 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1d270 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1d280 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1d290 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1d2a0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1d2b0 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1d2c0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1d2d0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1d2e0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1d2f0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1d300 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1d310 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1d320 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1d330 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1d340 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1d350 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1d360 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1d370 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d380 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1d390 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1d3a0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1d3b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1d3c0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1d3d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1d3e0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1d3f0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1d400 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1d410 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1d420 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1d430 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1d440 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1d450 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1d460 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1d470 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1d480 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1d490 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1d4a0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1d4b0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1d4c0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1d4d0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1d4e0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1d4f0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1d500 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1d510 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1d520 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1d530 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1d540 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1d550 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1d560 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1d570 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1d580 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1d590 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1d5a0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1d5b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1d5c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1d5d0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
1d5e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1d5f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1d600 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1d610 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1d620 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1d630 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1d640 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1d650 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1d660 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1d670 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1d680 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1d690 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1d6a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1d6b0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1d6c0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1d6d0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1d6e0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1d6f0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1d700 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1d710 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1d720 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1d730 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1d740 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1d750 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1d760 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1d770 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1d780 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d790 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1d7a0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1d7b0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1d7c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1d7d0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1d7e0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1d7f0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1d800 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1d810 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1d820 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  y..** These rout
1d830 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20  ines understand 
1d840 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d  most of the comm
1d850 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e  on K&R formattin
1d860 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c  g options,.** pl
1d870 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  us some addition
1d880 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20  al non-standard 
1d890 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65  formats, detaile
1d8a0 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65  d below..** Note
1d8b0 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68   that some of th
1d8c0 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66  e more obscure f
1d8d0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1d8e0 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a  s from recent.**
1d8f0 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64   C-library stand
1d900 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64  ards are omitted
1d910 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65   from this imple
1d920 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  mentation..**.**
1d930 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1d940 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1d950 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1d960 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
1d970 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
1d980 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1d990 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1d9a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
1d9b0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1d9c0 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
1d9d0 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
1d9e0 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
1d9f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
1da00 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
1da10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
1da20 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1da30 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1da40 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
1da50 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
1da60 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
1da70 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
1da80 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
1da90 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
1daa0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1dab0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
1dac0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
1dad0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1dae0 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
1daf0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
1db00 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
1db10 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
1db20 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1db30 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
1db40 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
1db50 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1db60 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
1db70 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
1db80 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
1db90 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
1dba0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
1dbb0 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
1dbc0 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
1dbd0 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
1dbe0 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
1dbf0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1dc00 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
1dc10 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
1dc20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
1dc30 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1dc40 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
1dc50 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
1dc60 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
1dc70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1dc80 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
1dc90 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
1dca0 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
1dcb0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
1dcc0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1dcd0 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
1dce0 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
1dcf0 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
1dd00 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
1dd10 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
1dd20 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1dd30 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1dd40 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
1dd50 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
1dd60 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1dd70 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
1dd80 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
1dd90 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
1dda0 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
1ddb0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
1ddc0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
1ddd0 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
1dde0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
1ddf0 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
1de00 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
1de10 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
1de20 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
1de30 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
1de40 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
1de50 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
1de60 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
1de70 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
1de80 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
1de90 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
1dea0 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
1deb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1dec0 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
1ded0 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
1dee0 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
1def0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
1df00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1df10 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
1df20 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
1df30 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
1df40 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
1df50 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
1df60 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
1df70 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
1df80 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
1df90 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
1dfa0 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
1dfb0 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
1dfc0 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
1dfd0 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22  "%q", "%Q", "%w"
1dfe0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
1dff0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
1e000 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
1e010 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
1e020 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
1e030 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
1e040 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
1e050 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
1e060 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
1e070 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
1e080 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
1e090 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
1e0a0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
1e0b0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
1e0c0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
1e0d0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
1e0e0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
1e0f0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
1e100 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
1e110 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
1e120 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
1e130 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
1e140 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
1e150 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
1e160 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
1e170 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1e180 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1e190 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1e1a0 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
1e1b0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
1e1c0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e1d0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
1e1e0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
1e1f0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1e200 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
1e210 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1e220 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1e230 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1e240 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1e250 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1e260 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
1e270 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1e280 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1e290 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1e2a0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1e2b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e2c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
1e2d0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
1e2e0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
1e2f0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
1e300 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
1e310 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
1e320 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
1e330 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
1e340 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e350 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1e360 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1e370 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
1e380 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
1e390 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1e3a0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1e3b0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
1e3c0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
1e3d0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
1e3e0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
1e3f0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
1e400 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
1e410 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e420 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1e430 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1e440 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
1e450 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
1e460 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1e470 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
1e480 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
1e490 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
1e4a0 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
1e4b0 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
1e4c0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
1e4d0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
1e4e0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
1e4f0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
1e500 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
1e510 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
1e520 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
1e530 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
1e540 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
1e550 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
1e560 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
1e570 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
1e580 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
1e590 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1e5a0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
1e5b0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
1e5c0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
1e5d0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
1e5e0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
1e5f0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
1e600 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
1e610 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
1e620 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
1e630 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e640 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1e650 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1e660 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1e670 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
1e680 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1e690 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1e6a0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1e6b0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1e6c0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e6d0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1e6e0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
1e6f0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
1e700 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
1e710 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
1e720 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
1e730 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
1e740 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
1e750 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
1e760 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1e770 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69  ing option is li
1e780 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74  ke "%q" except t
1e790 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74  hat it expects t
1e7a0 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65  o.** be containe
1e7b0 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d  d within double-
1e7c0 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f  quotes instead o
1e7d0 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c  f single quotes,
1e7e0 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70   and it.** escap
1e7f0 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75  es the double-qu
1e800 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e  ote character in
1e810 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e  stead of the sin
1e820 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61  gle-quote.** cha
1e830 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22  racter.)^  The "
1e840 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
1e850 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65  ption is intende
1e860 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73  d for safely ins
1e870 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20  erting.** table 
1e880 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73  and column names
1e890 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63   into a construc
1e8a0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1e8b0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  t..**.** ^(The "
1e8c0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1e8d0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1e8e0 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1e8f0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1e900 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1e910 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1e920 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1e930 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1e940 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1e950 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1e960 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1e970 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
1e980 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1e990 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1e9a0 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  ar*,...);.SQLITE
1e9b0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1e9c0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1e9d0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1e9e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1e9f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1ea00 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1ea10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1ea20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1ea30 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1ea40 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1ea50 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1ea60 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1ea70 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1ea80 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1ea90 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1eaa0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1eab0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1eac0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1ead0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1eae0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1eaf0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1eb00 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1eb10 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1eb20 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1eb30 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1eb40 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1eb50 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1eb60 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1eb70 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1eb80 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1eb90 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1eba0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1ebb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ebc0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1ebd0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1ebe0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1ebf0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1ec00 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1ec10 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1ec20 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1ec30 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ec40 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1ec50 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1ec60 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1ec70 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1ec80 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1ec90 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1eca0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1ecb0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1ecc0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1ecd0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ece0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1ecf0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1ed00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1ed10 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
1ed20 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
1ed30 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
1ed40 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
1ed50 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
1ed60 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
1ed70 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1ed80 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
1ed90 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
1eda0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1edb0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1edc0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1edd0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1ede0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1edf0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1ee00 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1ee10 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1ee20 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1ee30 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1ee40 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1ee50 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1ee60 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1ee70 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1ee80 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1ee90 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1eea0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1eeb0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1eec0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1eed0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1eee0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1eef0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1ef00 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1ef10 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1ef20 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1ef30 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1ef40 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1ef50 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1ef60 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1ef70 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1ef80 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1ef90 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1efa0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1efb0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1efc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1efd0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1efe0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1eff0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1f000 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1f010 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f020 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1f030 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
1f040 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f050 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
1f060 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1f070 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1f080 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f090 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
1f0a0 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
1f0b0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
1f0c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1f0d0 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
1f0e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1f0f0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1f100 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1f110 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1f120 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
1f130 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
1f140 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1f150 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
1f160 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1f170 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1f180 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1f190 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1f1a0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1f1b0 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
1f1c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f1d0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1f1e0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1f1f0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1f200 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1f210 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1f220 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
1f230 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
1f240 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1f250 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1f260 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1f270 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1f280 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1f290 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1f2a0 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1f2b0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1f2c0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1f2d0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1f2e0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1f2f0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1f300 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1f310 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1f320 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1f330 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
1f340 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
1f350 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
1f360 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
1f370 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1f380 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1f390 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
1f3a0 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
1f3b0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
1f3c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1f3d0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1f3e0 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
1f3f0 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
1f400 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
1f410 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1f420 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
1f430 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
1f440 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
1f450 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1f460 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1f470 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1f480 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
1f490 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
1f4a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1f4b0 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
1f4c0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1f4d0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
1f4e0 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
1f4f0 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
1f500 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
1f510 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1f520 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
1f530 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
1f540 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
1f550 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
1f560 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
1f570 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
1f580 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f590 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1f5a0 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1f5b0 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
1f5c0 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
1f5d0 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
1f5e0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1f5f0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
1f600 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
1f610 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
1f620 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
1f630 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
1f640 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
1f650 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
1f660 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
1f670 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1f680 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1f690 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
1f6a0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1f6b0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1f6c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f6d0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1f6e0 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1f6f0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
1f700 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f710 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
1f720 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1f730 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1f740 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1f750 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1f760 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1f770 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1f780 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1f790 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1f7a0 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1f7b0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1f7c0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1f7d0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1f7e0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1f7f0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1f800 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1f810 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1f820 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1f830 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1f840 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1f850 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1f860 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1f870 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1f880 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1f890 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1f8a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1f8b0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1f8c0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1f8d0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1f8e0 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1f8f0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1f900 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1f910 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1f920 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1f930 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1f940 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1f950 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1f960 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1f970 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1f980 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1f990 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1f9a0 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1f9b0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1f9c0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1f9d0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1f9e0 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1f9f0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1fa00 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1fa10 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1fa20 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1fa30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1fa40 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1fa50 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1fa60 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1fa70 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1fa80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1fa90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1faa0 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1fab0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1fac0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1fad0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1fae0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1faf0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1fb00 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1fb10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1fb20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1fb30 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1fb40 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1fb50 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1fb60 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1fb70 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1fb80 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1fb90 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1fba0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1fbb0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1fbc0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1fbd0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1fbe0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1fbf0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1fc00 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  c(int);.SQLITE_A
1fc10 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1fc20 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1fc30 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  3_uint64);.SQLIT
1fc40 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1fc50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1fc60 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
1fc70 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1fc80 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64  3_realloc64(void
1fc90 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
1fca0 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
1fcb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1fcc0 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f  (void*);.SQLITE_
1fcd0 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  API sqlite3_uint
1fce0 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  64 sqlite3_msize
1fcf0 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1fd00 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1fd10 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1fd20 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1fd30 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1fd40 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1fd50 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1fd60 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1fd70 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1fd80 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1fd90 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1fda0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1fdb0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1fdc0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1fdd0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1fde0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1fdf0 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1fe00 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1fe10 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1fe20 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1fe30 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1fe40 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1fe50 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1fe60 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1fe70 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1fe80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1fe90 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1fea0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1feb0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1fec0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1fed0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1fee0 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1fef0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1ff00 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1ff10 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1ff20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1ff30 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1ff40 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1ff50 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1ff60 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1ff70 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1ff80 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1ff90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1ffa0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1ffb0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1ffc0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1ffd0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1ffe0 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1fff0 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
20000 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
20010 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
20020 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
20030 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
20040 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
20050 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
20060 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
20070 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
20080 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
20090 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
200a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
200b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
200c0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
200d0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
200e0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
200f0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20100 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
20110 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
20120 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
20130 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
20140 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
20150 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20160 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  d(void);.SQLITE_
20170 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
20180 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
20190 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
201a0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
201b0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
201c0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
201d0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
201e0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
201f0 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
20200 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
20210 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
20220 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
20230 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
20240 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
20250 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
20260 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
20270 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
20280 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
20290 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
202a0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
202b0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
202c0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
202d0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
202e0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
202f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
20300 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
20310 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
20320 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
20330 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
20340 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
20350 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
20360 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
20370 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
20380 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
20390 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
203a0 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
203b0 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
203c0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
203d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
203e0 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
203f0 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
20400 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
20410 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
20420 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
20430 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
20440 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
20450 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
20460 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
20470 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
20480 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
20490 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
204a0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
204b0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
204c0 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
204d0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
204e0 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
204f0 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
20500 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
20510 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
20520 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
20530 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
20540 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
20550 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
20560 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
20570 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
20580 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54  method..*/.SQLIT
20590 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
205a0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
205b0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
205c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
205d0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
205e0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
205f0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
20600 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f  sqlite3.** KEYWO
20610 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72  RDS: {authorizer
20620 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a   callback}.**.**
20630 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
20640 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
20650 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20660 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
20670 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
20680 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
20690 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
206a0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
206b0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
206c0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
206d0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
206e0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
206f0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
20700 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
20710 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
20720 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
20730 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
20740 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
20750 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
20760 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c  epare16()], [sql
20770 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20780 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71  2()],.** and [sq
20790 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
207a0 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v3()].  ^At vari
207b0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
207c0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
207d0 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
207e0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
207f0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
20800 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
20810 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
20820 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20830 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
20840 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
20850 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
20860 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
20870 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
20880 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
20890 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
208a0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
208b0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
208c0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
208d0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
208e0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
208f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
20900 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
20910 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
20920 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
20930 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
20940 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
20950 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
20960 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
20970 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
20980 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
20990 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
209a0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
209b0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
209c0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
209d0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
209e0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
209f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
20a00 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
20a10 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
20a20 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
20a30 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
20a40 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
20a50 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
20a60 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
20a70 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
20a80 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
20a90 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
20aa0 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
20ab0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
20ac0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
20ad0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
20ae0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20af0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
20b00 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
20b10 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
20b20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
20b30 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
20b40 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
20b50 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
20b60 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
20b70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
20b80 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
20b90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20ba0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
20bb0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
20bc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20bd0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
20be0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
20bf0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
20c00 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
20c10 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
20c20 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
20c30 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
20c40 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
20c50 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
20c60 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
20c70 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
20c80 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
20c90 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
20ca0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
20cb0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69   callback are ei
20cc0 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ther NULL pointe
20cd0 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69  rs or zero-termi
20ce0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  nated strings.**
20cf0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
20d00 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
20d10 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
20d20 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
20d30 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  ed..** Applicati
20d40 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ons must always 
20d50 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 65  be prepared to e
20d60 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20  ncounter a NULL 
20d70 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a  pointer in any.*
20d80 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74  * of the third t
20d90 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 68  hrough the sixth
20da0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
20db0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
20dc0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
20dd0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
20de0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
20df0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
20e00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20e10 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
20e20 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
20e30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20e40 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
20e50 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
20e60 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
20e70 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
20e80 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
20e90 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
20ea0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
20eb0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
20ec0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
20ed0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
20ee0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
20ef0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
20f00 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
20f10 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
20f20 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
20f30 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
20f40 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20  table..** ^When 
20f50 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72  a table is refer
20f60 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45  enced by a [SELE
20f70 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d  CT] but no colum
20f80 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20  n values are.** 
20f90 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74  extracted from t
20fa0 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65  hat table (for e
20fb0 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72  xample in a quer
20fc0 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43  y like.** "SELEC
20fd0 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20  T count(*) FROM 
20fe0 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b  tab") then the [
20ff0 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74  SQLITE_READ] aut
21000 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21010 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  .** is invoked o
21020 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 62  nce for that tab
21030 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e  le with a column
21040 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e   name that is an
21050 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
21060 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
21070 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
21080 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
21090 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
210a0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
210b0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
210c0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
210d0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
210e0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
210f0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
21100 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
21110 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
21120 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
21130 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
21140 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
21150 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21160 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
21170 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
21180 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
21190 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
211a0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
211b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
211c0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
211d0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
211e0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
211f0 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
21200 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
21210 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
21220 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
21230 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
21240 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
21250 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
21260 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
21270 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
21280 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
21290 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
212a0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
212b0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
212c0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
212d0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
212e0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
212f0 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
21300 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
21310 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
21320 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
21330 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
21340 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
21350 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
21360 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
21370 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
21380 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
21390 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
213a0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
213b0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
213c0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
213d0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
213e0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
213f0 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
21400 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
21410 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
21420 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
21430 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
21440 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
21450 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
21460 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
21470 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
21480 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
21490 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
214a0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
214b0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
214c0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
214d0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
214e0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
214f0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
21500 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
21510 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
21520 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
21530 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
21540 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
21550 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
21560 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
21570 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
21580 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
21590 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
215a0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
215b0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
215c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
215d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
215e0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
215f0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
21600 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
21610 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21620 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
21630 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21640 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
21650 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
21660 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
21670 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
21680 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
21690 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
216a0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
216b0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
216c0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
216d0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
216e0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
216f0 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
21700 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
21710 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
21720 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
21730 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
21740 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
21750 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
21760 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
21770 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
21780 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
21790 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
217a0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
217b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
217c0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
217d0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
217e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
217f0 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
21800 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
21810 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
21820 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
21830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21840 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
21850 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
21860 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
21870 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
21880 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
21890 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
218a0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
218b0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
218c0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
218d0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
218e0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
218f0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
21900 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
21910 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
21920 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
21930 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51  ma change..*/.SQ
21940 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
21950 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21960 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
21970 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
21980 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
21990 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
219a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
219b0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
219c0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
219d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
219e0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
219f0 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
21a00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
21a10 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
21a20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21a30 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
21a40 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
21a50 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
21a60 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
21a70 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
21a80 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
21a90 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
21aa0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
21ab0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
21ac0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
21ad0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
21ae0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
21af0 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
21b00 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
21b10 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
21b20 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
21b30 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
21b40 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
21b50 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
21b60 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
21b70 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
21b80 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
21b90 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
21ba0 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
21bb0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
21bc0 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
21bd0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
21be0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
21bf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21c00 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
21c10 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
21c20 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
21c30 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
21c40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21c50 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
21c60 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
21c70 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
21c80 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
21c90 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
21ca0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
21cb0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
21cc0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
21cd0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
21ce0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
21cf0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
21d00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
21d10 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
21d20 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
21d30 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
21d40 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
21d50 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
21d60 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
21d70 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
21d80 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
21d90 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21da0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
21db0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
21dc0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
21dd0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
21de0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
21df0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
21e00 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
21e10 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
21e20 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
21e30 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
21e40 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
21e50 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
21e60 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
21e70 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
21e80 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
21e90 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
21ea0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
21eb0 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
21ec0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21ed0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
21ee0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
21ef0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
21f00 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
21f10 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
21f20 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
21f30 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
21f40 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
21f50 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
21f60 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
21f70 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
21f80 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
21f90 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
21fa0 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
21fb0 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
21fc0 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
21fd0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
21fe0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
21ff0 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
22000 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
22010 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22020 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22030 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
22040 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
22050 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
22060 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
22070 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
22080 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
22090 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
220a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
220b0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
220c0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
220d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
220e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
220f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22100 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
22110 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
22120 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22130 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22150 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
22160 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
22170 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22180 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
221a0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
221b0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
221c0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
221d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
221e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
221f0 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
22200 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
22210 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
22220 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22240 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
22250 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
22260 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
22270 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22290 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
222a0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
222b0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
222c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
222d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
222e0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
222f0 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
22300 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22310 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22320 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22330 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
22340 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
22350 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
22360 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22370 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22380 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
22390 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
223a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
223b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
223c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
223d0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
223e0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
223f0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
22400 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22410 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
22420 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
22430 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22440 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22450 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22460 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
22470 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
22480 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22490 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
224a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
224b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
224c0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
224d0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
224e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
224f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22500 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
22510 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
22520 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
22530 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22540 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22550 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
22560 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
22570 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22580 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22590 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
225a0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
225b0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
225c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
225d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
225e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
225f0 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
22600 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
22610 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
22620 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
22630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22640 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
22650 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
22660 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
22670 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
22680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22690 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
226a0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
226b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
226c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
226d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
226e0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
226f0 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
22700 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
22710 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
22730 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
22740 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
22750 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
22760 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
22770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
22780 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
22790 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
227a0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
227b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
227c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
227d0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
227e0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
227f0 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
22800 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22810 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
22820 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
22830 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
22840 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
22850 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22860 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
22870 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
22880 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
22890 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
228a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
228b0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
228c0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
228d0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
228e0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
228f0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22900 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22910 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
22920 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22930 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
22940 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22950 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
22960 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
22970 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22980 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
22990 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
229a0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
229b0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
229c0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
229d0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
229e0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
229f0 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
22a00 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
22a10 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
22a20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
22a30 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
22a40 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
22a50 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
22a60 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
22a70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22a80 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
22a90 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
22aa0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22ab0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22ac0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
22ad0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
22ae0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
22af0 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
22b00 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
22b10 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
22b20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20  deprecated. Use 
22b30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
22b40 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  ce_v2()] interfa
22b50 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  ce.** instead of
22b60 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65   the routines de
22b70 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a  scribed here..**
22b80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
22b90 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
22ba0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
22bb0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
22bc0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
22bd0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
22be0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
22bf0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
22c00 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
22c10 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
22c20 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
22c30 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
22c40 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
22c50 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
22c60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
22c70 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
22c80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
22c90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22ca0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
22cb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
22cc0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
22cd0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
22ce0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
22cf0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
22d00 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
22d10 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
22d20 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
22d30 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
22d40 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
22d50 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
22d60 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
22d70 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
22d80 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
22d90 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
22da0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
22db0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
22dc0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
22dd0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
22de0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
22df0 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
22e00 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
22e10 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
22e20 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
22e30 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
22e40 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
22e50 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
22e60 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
22e70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
22e80 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
22e90 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
22ea0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
22eb0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
22ec0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
22ed0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
22ee0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
22ef0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
22f00 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
22f10 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
22f20 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
22f30 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
22f40 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
22f50 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
22f60 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
22f70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
22f80 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
22f90 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
22fa0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
22fb0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
22fc0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
22fd0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
22fe0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
22ff0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
23000 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
23010 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
23020 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
23030 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
23040 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
23050 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
23060 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
23070 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
23080 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
23090 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
230a0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
230b0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
230c0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
230d0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
230e0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
230f0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
23100 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
23110 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
23120 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
23130 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
23140 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
23150 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
23160 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
23170 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
23180 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
23190 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
231a0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
231b0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
231c0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
231d0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
231e0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
231f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23200 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20  SQL Trace Event 
23210 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
23220 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a  S: SQLITE_TRACE.
23230 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
23240 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63  tants identify c
23250 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73  lasses of events
23260 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e   that can be mon
23270 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20  itored.** using 
23280 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
23290 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67  ce_v2()] tracing
232a0 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69   logic.  The thi
232b0 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
232c0 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
232d0 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d  _v2()] is an OR-
232e0 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
232f0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
23300 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
23310 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54  g constants.  ^T
23320 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
23330 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
23340 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e  allback.** is on
23350 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
23360 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  ng constants..**
23370 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20  .** New tracing 
23380 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
23390 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
233a0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
233b0 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
233c0 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75  ck has four argu
233d0 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b  ments: xCallback
233e0 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
233f0 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
23400 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65   one of the inte
23410 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61  ger type codes a
23420 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  bove..** ^The C 
23430 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
23440 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
23450 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  t pointer passed
23460 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f   in as the.** fo
23470 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
23480 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
23490 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20  v2()]..** The P 
234a0 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
234b0 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
234c0 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
234d0 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c  nd on T..**.** <
234e0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
234f0 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74  TRACE_STMT]] <dt
23500 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54  >SQLITE_TRACE_ST
23510 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  MT</dt>.** <dd>^
23520 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
23530 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73  STMT callback is
23540 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
23550 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23560 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69  nt.** first begi
23570 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70  ns running and p
23580 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72  ossibly at other
23590 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68   times during th
235a0 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f  e.** execution o
235b0 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
235c0 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61  tatement, such a
235d0 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f  s at the start o
235e0 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65  f each.** trigge
235f0 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54  r subprogram. ^T
23600 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
23610 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23620 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
23630 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20  tatement]. ^The 
23640 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  X argument is a 
23650 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
23660 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ing which.** is 
23670 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53  the unexpanded S
23680 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70  QL text of the p
23690 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
236a0 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d  t or an SQL comm
236b0 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ent .** that ind
236c0 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63  icates the invoc
236d0 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67  ation of a trigg
236e0 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61  er.  ^The callba
236f0 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a  ck can compute.*
23700 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20  * the same text 
23710 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20  that would have 
23720 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79  been returned by
23730 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
23740 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a  ite3_trace()].**
23750 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73   interface by us
23760 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65  ing the X argume
23770 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73  nt when X begins
23780 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69   with "--" and i
23790 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  nvoking.** [sqli
237a0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
237b0 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a  (P)] otherwise..
237c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
237d0 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c  RACE_PROFILE]] <
237e0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
237f0 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20  PROFILE</dt>.** 
23800 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
23810 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
23820 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61  lback provides a
23830 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65  pproximately the
23840 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61   same.** informa
23850 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69  tion as is provi
23860 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ded by the [sqli
23870 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63  te3_profile()] c
23880 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
23890 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
238a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
238b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
238c0 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
238d0 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  X argument point
238e0 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e  s to a 64-bit in
238f0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74  teger which is t
23900 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a  he estimated of.
23910 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
23920 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74   nanosecond that
23930 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
23940 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
23950 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  run..** ^The SQL
23960 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
23970 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
23980 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73  voked when the s
23990 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
239a0 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  s..**.** [[SQLIT
239b0 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64  E_TRACE_ROW]] <d
239c0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  t>SQLITE_TRACE_R
239d0 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  OW</dt>.** <dd>^
239e0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
239f0 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ROW callback is 
23a00 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
23a10 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
23a20 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74  tatement generat
23a30 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  es a single row 
23a40 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20  of result.  .** 
23a50 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
23a60 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23a70 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23a80 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
23a90 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69  .** X argument i
23aa0 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s unused..**.** 
23ab0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  [[SQLITE_TRACE_C
23ac0 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LOSE]] <dt>SQLIT
23ad0 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64  E_TRACE_CLOSE</d
23ae0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
23af0 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
23b00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
23b10 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61  oked when a data
23b20 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
23b30 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54  on closes..** ^T
23b40 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
23b50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23b60 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
23b70 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a  ection] object.*
23b80 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75  * and the X argu
23b90 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
23ba0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
23bb0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
23bc0 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31  _STMT       0x01
23bd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23be0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20  TRACE_PROFILE   
23bf0 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51   0x02.#define SQ
23c00 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20  LITE_TRACE_ROW  
23c10 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69        0x04.#defi
23c20 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
23c30 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a  CLOSE      0x08.
23c40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23c50 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a   SQL Trace Hook.
23c60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
23c70 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
23c80 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44  lite3_trace_v2(D
23c90 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,M,X,P) interfac
23ca0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72  e registers a tr
23cb0 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
23cc0 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e  function X again
23cd0 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  st [database con
23ce0 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e  nection] D, usin
23cf0 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20  g property mask 
23d00 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74  M.** and context
23d10 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66   pointer P.  ^If
23d20 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20   the X callback 
23d30 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66  is.** NULL or if
23d40 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a   the M mask is z
23d50 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e  ero, then tracin
23d60 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  g is disabled.  
23d70 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e  The.** M argumen
23d80 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
23d90 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f  bitwise OR-ed co
23da0 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
23db0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51  zero or more [SQ
23dc0 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73  LITE_TRACE] cons
23dd0 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61  tants..**.** ^Ea
23de0 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ch call to eithe
23df0 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  r sqlite3_trace(
23e00 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
23e10 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65  ce_v2() override
23e20 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20  s .** (cancels) 
23e30 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
23e40 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  to sqlite3_trace
23e50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
23e60 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ace_v2()..**.** 
23e70 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20  ^The X callback 
23e80 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
23e90 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65  ver any of the e
23ea0 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64  vents identified
23eb0 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f   by .** mask M o
23ec0 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65  ccur.  ^The inte
23ed0 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ger return value
23ee0 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61   from the callba
23ef0 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a  ck is currently.
23f00 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75  ** ignored, thou
23f10 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e  gh this may chan
23f20 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ge in future rel
23f30 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b  eases.  Callback
23f40 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
23f50 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ons should retur
23f60 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65  n zero to ensure
23f70 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62   future compatib
23f80 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  ility..**.** ^A 
23f90 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
23fa0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66  s invoked with f
23fb0 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63  our arguments: c
23fc0 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
23fd0 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
23fe0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
23ff0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
24000 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74  ].** constants t
24010 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74  o indicate why t
24020 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20  he callback was 
24030 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
24040 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
24050 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
24060 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  text pointer..**
24070 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
24080 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
24090 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
240a0 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
240b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
240c0 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74  3_trace_v2() int
240d0 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
240e0 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68  ed to replace th
240f0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
24100 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
24110 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71  trace()] and [sq
24120 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
24130 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a  , both of which.
24140 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65  ** are deprecate
24150 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
24160 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
24170 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ce_v2(.  sqlite3
24180 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d  *,.  unsigned uM
24190 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c  ask,.  int(*xCal
241a0 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c  lback)(unsigned,
241b0 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64  void*,void*,void
241c0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78  *),.  void *pCtx
241d0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
241e0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
241f0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
24200 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
24210 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
24220 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
24230 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
24240 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
24250 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
24260 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
24270 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
24280 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
24290 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
242a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
242b0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
242c0 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
242d0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
242e0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
242f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
24300 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
24310 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
24320 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
24330 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
24340 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
24350 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
24360 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
24370 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
24380 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
24390 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
243a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
243b0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
243c0 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
243d0 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
243e0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
243f0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
24400 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
24410 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
24420 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
24430 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
24440 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
24450 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
24460 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
24470 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
24480 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
24490 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
244a0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
244b0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
244c0 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
244d0 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
244e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
244f0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
24500 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
24510 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
24520 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
24530 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
24540 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
24550 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
24560 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
24570 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
24580 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
24590 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
245a0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
245b0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
245c0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
245d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
245e0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
245f0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
24600 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
24610 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
24620 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
24630 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
24640 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
24650 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
24660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
24670 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
24680 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
24690 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
246a0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
246b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
246c0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
246d0 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
246e0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
246f0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
24700 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
24710 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
24720 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
24730 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
24740 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
24750 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
24760 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
24770 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
24780 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
24790 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
247a0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
247b0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
247c0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
247d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
247e0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
247f0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
24800 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  ion.** CONSTRUCT
24810 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
24820 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
24830 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
24840 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
24850 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
24860 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
24870 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
24880 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
24890 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
248a0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
248b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
248c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
248d0 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
248e0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
248f0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
24900 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
24910 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
24920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
24930 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
24940 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
24950 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
24960 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
24970 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
24980 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
24990 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
249a0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
249b0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
249c0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
249d0 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
249e0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
249f0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
24a00 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
24a10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
24a20 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
24a30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
24a40 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
24a50 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
24a60 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
24a70 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
24a80 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
24a90 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
24aa0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
24ab0 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
24ac0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
24ad0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
24ae0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
24af0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
24b00 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
24b10 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
24b20 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
24b30 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
24b40 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
24b50 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
24b60 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
24b70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
24b80 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
24b90 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
24ba0 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
24bb0 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
24bc0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
24bd0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
24be0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
24bf0 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
24c00 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
24c10 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
24c20 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
24c30 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
24c40 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
24c50 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
24c60 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
24c70 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
24c80 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
24c90 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
24ca0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
24cb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
24cc0 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
24cd0 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
24ce0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
24cf0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
24d00 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
24d10 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
24d20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24d30 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
24d40 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
24d50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
24d60 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
24d70 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
24d80 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
24d90 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
24da0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
24db0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
24dc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
24dd0 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
24de0 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
24df0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
24e00 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
24e10 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
24e20 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
24e30 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
24e40 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
24e50 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
24e60 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
24e70 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
24e80 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
24e90 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
24ea0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
24eb0 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
24ec0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
24ed0 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
24ee0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
24ef0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
24f00 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
24f10 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
24f20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
24f30 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
24f40 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
24f50 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
24f60 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
24f70 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
24f80 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
24f90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24fa0 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
24fb0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
24fc0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
24fd0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
24fe0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
24ff0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
25000 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
25010 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
25020 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
25030 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
25040 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
25050 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
25060 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
25070 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
25080 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
25090 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
250a0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
250b0 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
250c0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
250d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
250e0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
250f0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
25100 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
25110 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
25120 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
25130 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
25140 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
25150 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
25160 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
25170 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
25180 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
25190 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
251a0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
251b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
251c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
251d0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
251e0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
251f0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
25200 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
25210 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
25220 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
25230 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
25240 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
25250 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
25260 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
25270 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
25280 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
25290 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
252a0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
252b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
252c0 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
252d0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
252e0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
252f0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
25300 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
25310 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
25320 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
25330 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
25340 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
25350 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
25360 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
25370 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
25380 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
25390 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
253a0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
253b0 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
253c0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
253d0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
253e0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
253f0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
25400 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
25410 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
25420 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
25430 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
25440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
25450 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
25460 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
25470 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
25480 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
25490 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
254a0 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
254b0 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
254c0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
254d0 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
254e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
254f0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
25500 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
25510 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25520 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
25530 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
25540 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
25550 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
25560 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
25570 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
25580 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
25590 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
255a0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
255b0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
255c0 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
255d0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
255e0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
255f0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
25600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25610 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
25620 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
25630 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
25640 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
25650 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
25660 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
25670 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
25680 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
25690 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
256a0 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
256b0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
256c0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
256d0 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
256e0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
256f0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
25700 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
25710 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
25720 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25730 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
25740 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
25750 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
25760 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
25770 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
25780 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
25790 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
257a0 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
257b0 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
257c0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
257d0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
257e0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
257f0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
25800 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
25810 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
25820 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
25830 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
25840 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
25850 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
25860 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
25870 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
25880 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
25890 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
258a0 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
258b0 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
258c0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
258d0 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
258e0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
258f0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
25900 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
25910 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
25920 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
25930 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
25940 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
25950 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
25960 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
25970 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
25980 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
25990 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
259a0 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
259b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
259c0 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
259d0 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
259e0 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
259f0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
25a00 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
25a10 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
25a20 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
25a30 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
25a40 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
25a50 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
25a60 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
25a70 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
25a80 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
25a90 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
25aa0 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
25ab0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
25ac0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
25ad0 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
25ae0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
25af0 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
25b00 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
25b10 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
25b20 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
25b30 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
25b40 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
25b50 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
25b60 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
25b70 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
25b80 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
25b90 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
25ba0 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
25bb0 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
25bc0 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
25bd0 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
25be0 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
25bf0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
25c00 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
25c10 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
25c20 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
25c30 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
25c40 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
25c50 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
25c60 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
25c70 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
25c80 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25c90 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
25ca0 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
25cb0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
25cc0 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
25cd0 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
25ce0 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
25cf0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
25d00 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
25d10 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
25d20 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
25d30 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
25d40 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
25d50 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
25d60 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
25d70 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
25d80 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
25d90 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
25da0 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
25db0 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
25dc0 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
25dd0 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
25de0 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
25df0 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
25e00 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
25e10 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
25e20 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
25e30 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
25e40 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
25e50 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
25e60 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
25e70 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
25e80 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
25e90 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
25ea0 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
25eb0 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
25ec0 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
25ed0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
25ee0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
25ef0 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
25f00 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
25f10 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
25f20 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
25f30 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
25f40 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
25f50 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
25f60 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
25f70 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
25f80 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
25f90 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
25fa0 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
25fb0 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
25fc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
25fd0 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
25fe0 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
25ff0 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
26000 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
26010 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
26020 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
26030 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
26040 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
26050 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
26060 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
26070 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
26080 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
26090 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
260a0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
260b0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
260c0 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
260d0 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
260e0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
260f0 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
26100 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
26110 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
26120 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
26130 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
26140 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
26150 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
26160 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
26170 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
26180 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26190 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
261a0 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
261b0 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
261c0 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
261d0 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
261e0 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
261f0 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
26200 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
26210 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
26220 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
26230 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
26240 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
26250 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
26260 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
26270 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
26280 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
26290 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
262a0 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
262b0 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
262c0 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
262d0 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
262e0 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
262f0 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
26300 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
26310 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
26320 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
26330 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
26340 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
26350 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
26360 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
26370 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
26380 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
26390 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
263a0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
263b0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
263c0 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
263d0 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
263e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
263f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
26400 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
26410 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
26420 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
26430 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
26440 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
26450 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
26460 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
26470 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
26480 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
26490 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
264a0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
264b0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
264c0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
264d0 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
264e0 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
264f0 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
26500 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
26510 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
26520 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
26530 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
26540 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
26550 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
26560 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
26570 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
26580 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
26590 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
265a0 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
265b0 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
265c0 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
265d0 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
265e0 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
265f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
26600 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
26610 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
26620 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
26630 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
26640 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
26650 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
26660 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
26670 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
26680 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
26690 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
266a0 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
266b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
266c0 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
266d0 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
266e0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
266f0 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
26700 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
26710 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
26720 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
26730 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
26740 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
26750 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
26760 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
26770 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
26780 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
26790 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
267a0 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
267b0 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
267c0 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
267d0 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
267e0 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
267f0 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
26800 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
26810 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
26820 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
26830 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26840 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
26850 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
26860 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
26870 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
26880 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
26890 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
268a0 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
268b0 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
268c0 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
268d0 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
268e0 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
268f0 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
26900 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
26910 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
26920 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
26930 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
26940 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
26950 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
26960 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
26970 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
26980 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
26990 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
269a0 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
269b0 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
269c0 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
269d0 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
269e0 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
269f0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
26a00 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
26a10 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
26a20 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
26a30 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
26a40 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
26a50 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
26a60 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
26a70 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
26a80 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
26a90 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
26aa0 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
26ab0 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
26ac0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
26ad0 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
26ae0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
26af0 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
26b00 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
26b10 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
26b20 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
26b30 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
26b40 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
26b50 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
26b60 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
26b70 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
26b80 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
26b90 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
26ba0 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
26bb0 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
26bc0 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
26bd0 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
26be0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
26bf0 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
26c00 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
26c10 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
26c20 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
26c30 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
26c40 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
26c50 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
26c60 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
26c70 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
26c80 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
26c90 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
26ca0 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
26cb0 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
26cc0 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
26cd0 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
26ce0 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
26cf0 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
26d00 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
26d10 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
26d20 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
26d30 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
26d40 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
26d50 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
26d60 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
26d70 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
26d80 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
26d90 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
26da0 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
26db0 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
26dc0 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
26dd0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
26de0 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
26df0 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
26e00 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
26e10 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
26e20 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
26e30 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
26e40 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
26e50 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
26e60 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
26e70 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
26e80 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
26e90 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
26ea0 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
26eb0 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
26ec0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
26ed0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
26ee0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
26ef0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
26f00 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
26f10 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
26f20 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
26f30 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
26f40 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
26f50 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
26f60 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
26f70 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
26f80 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
26f90 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
26fa0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26fb0 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
26fc0 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
26fd0 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
26fe0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
26ff0 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
27000 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
27010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
27020 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
27030 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
27040 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
27050 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
27060 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
27070 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
27080 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
27090 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
270a0 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
270b0 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
270c0 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
270d0 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
270e0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
270f0 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
27100 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
27110 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
27120 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
27130 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
27140 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
27150 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
27160 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
27170 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
27180 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
27190 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
271a0 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
271b0 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
271c0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
271d0 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
271e0 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
271f0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
27200 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
27210 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
27220 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
27230 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
27240 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
27250 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
27260 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
27270 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
27280 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
27290 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
272a0 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
272b0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
272c0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
272d0 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
272e0 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
272f0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
27300 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27310 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
27320 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
27330 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
27340 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
27350 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
27360 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
27370 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
27380 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
27390 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
273a0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
273b0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
273c0 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
273d0 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
273e0 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
273f0 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
27400 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
27410 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
27420 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
27430 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
27440 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
27450 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
27460 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
27470 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
27480 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
27490 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
274a0 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
274b0 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
274c0 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
274d0 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
274e0 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
274f0 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
27500 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
27510 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
27520 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
27530 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
27540 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
27550 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
27560 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
27570 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
27580 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
27590 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
275a0 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
275b0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
275c0 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
275d0 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
275e0 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
275f0 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
27600 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
27610 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
27620 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
27630 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
27640 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
27650 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
27660 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
27670 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
27680 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
27690 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
276a0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
276b0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
276c0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
276d0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
276e0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
276f0 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
27700 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
27710 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
27720 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
27730 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
27740 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
27750 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
27760 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
27770 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
27780 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
27790 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
277a0 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
277b0 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
277c0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
277d0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
277e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
277f0 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
27800 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
27810 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
27820 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
27830 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
27840 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
27850 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
27860 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
27870 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ry].*/.SQLITE_AP
27880 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
27890 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
278a0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
278b0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
278c0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
278d0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
278e0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
278f0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
27900 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
27910 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
27920 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
27930 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
27940 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
27950 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
27960 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
27970 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
27980 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
27990 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
279a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
279b0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
279c0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
279d0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
279e0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
279f0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
27a00 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
27a10 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
27a20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
27a30 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
27a40 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
27a50 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
27a60 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
27a70 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
27a80 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
27a90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
27aa0 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
27ab0 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
27ac0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
27ad0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
27ae0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
27af0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
27b00 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
27b10 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
27b20 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
27b30 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
27b40 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
27b50 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
27b60 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
27b70 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
27b80 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
27b90 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
27ba0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
27bb0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
27bc0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
27bd0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
27be0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
27bf0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
27c00 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
27c10 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
27c20 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
27c30 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
27c40 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
27c50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
27c60 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
27c70 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
27c80 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
27c90 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
27ca0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
27cb0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27cc0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
27cd0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
27ce0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
27cf0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
27d00 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
27d10 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
27d20 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
27d30 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
27d40 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
27d50 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
27d60 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
27d70 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
27d80 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27d90 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
27da0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
27db0 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
27dc0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27dd0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
27de0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
27df0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
27e00 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
27e10 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
27e20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
27e30 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
27e40 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
27e50 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
27e60 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27e70 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
27e80 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
27e90 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
27ea0 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
27eb0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
27ec0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
27ed0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
27ee0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
27ef0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
27f00 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
27f10 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
27f20 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27f30 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
27f40 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
27f50 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
27f60 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
27f70 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
27f80 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
27f90 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
27fa0 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
27fb0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
27fc0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
27fd0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
27fe0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
27ff0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
28000 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
28010 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
28020 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
28030 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
28040 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
28050 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
28060 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
28070 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
28080 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
28090 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
280a0 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
280b0 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
280c0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
280d0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
280e0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
280f0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
28100 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
28110 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
28120 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
28130 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
28140 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
28150 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
28160 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
28170 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
28180 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
28190 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
281a0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
281b0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
281c0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
281d0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
281e0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
281f0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
28200 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
28210 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
28220 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
28230 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
28240 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
28250 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
28260 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
28270 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
28280 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
28290 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
282a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
282b0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
282c0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
282d0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
282e0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53  char *zParam);.S
282f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
28300 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28310 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
28320 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
28330 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
28340 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41  fault);.SQLITE_A
28350 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
28360 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
28370 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
28380 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
28390 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
283a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
283b0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
283c0 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f  essages.** METHO
283d0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
283e0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
283f0 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41  cent sqlite3_* A
28400 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
28410 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74  ed with .** [dat
28420 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28430 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  ] D failed, then
28440 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   the sqlite3_err
28450 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63  code(D) interfac
28460 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
28470 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
28480 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
28490 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
284a0 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49   for that.** API
284b0 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65   call..** If the
284c0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
284d0 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73   call was succes
284e0 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  sful,.** then th
284f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
28500 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
28510 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
28520 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
28530 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
28540 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
28550 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
28560 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
28570 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
28580 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
28590 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
285a0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
285b0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
285c0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
285d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
285e0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
285f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
28600 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
28610 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
28620 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
28630 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
28640 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
28650 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
28660 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
28670 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
28680 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
28690 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
286a0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
286b0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
286c0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
286d0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
286e0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
286f0 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
28700 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
28710 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
28720 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
28730 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
28740 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
28750 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
28760 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
28770 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
28780 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
28790 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
287a0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
287b0 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
287c0 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
287d0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
287e0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
287f0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
28800 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
28810 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
28820 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
28830 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
28840 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
28850 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
28860 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
28870 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
28880 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
28890 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
288a0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
288b0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
288c0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
288d0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
288e0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
288f0 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
28900 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
28910 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
28920 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
28930 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
28940 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
28950 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
28960 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
28970 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
28980 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
28990 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
289a0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
289b0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
289c0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
289d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
289e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
289f0 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
28a00 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
28a10 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
28a20 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
28a30 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
28a40 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
28a50 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
28a60 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
28a70 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
28a80 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
28a90 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
28aa0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
28ab0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
28ac0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
28ad0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
28ae0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
28af0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
28b00 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
28b10 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
28b20 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
28b30 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
28b40 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
28b50 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
28b60 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
28b70 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51  ot be set..*/.SQ
28b80 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28b90 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
28ba0 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
28bb0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
28bc0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
28bd0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
28be0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
28bf0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28c00 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
28c10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
28c20 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28c30 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
28c40 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
28c50 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28c60 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
28c70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28c80 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
28c90 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
28ca0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
28cb0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
28cc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28cd0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
28ce0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
28cf0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
28d00 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
28d10 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
28d20 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
28d30 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
28d40 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
28d50 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
28d60 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
28d70 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
28d80 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
28d90 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
28da0 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
28db0 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
28dc0 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
28dd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28de0 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
28df0 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
28e00 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
28e10 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
28e20 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
28e30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28e40 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
28e50 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
28e60 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
28e70 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
28e80 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
28e90 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
28ea0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
28eb0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
28ec0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28ed0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
28ee0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
28ef0 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v2()]..** <li
28f00 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
28f10 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
28f20 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
28f30 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
28f40 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
28f50 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
28f60 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
28f70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
28f80 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
28f90 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
28fa0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28fb0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
28fc0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
28fd0 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
28fe0 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
28ff0 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
29000 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
29010 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
29020 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
29030 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
29040 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
29050 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
29060 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
29070 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
29080 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
29090 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
290a0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
290b0 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
290c0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
290d0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
290e0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
290f0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
29100 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
29110 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
29120 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
29130 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
29140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29150 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
29160 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
29170 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
29180 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
29190 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
291a0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
291b0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
291c0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
291d0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
291e0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
291f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29200 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
29210 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
29220 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
29230 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
29240 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
29250 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
29260 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
29270 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
29280 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
29290 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
292a0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
292b0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
292c0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
292d0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
292e0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
292f0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
29300 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
29310 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
29320 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
29330 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
29340 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
29350 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
29360 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
29370 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
29380 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
29390 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
293a0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
293b0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
293c0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
293d0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
293e0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
293f0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
29400 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
29410 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
29420 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
29430 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
29440 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
29450 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
29460 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
29470 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
29480 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
29490 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
294a0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
294b0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
294c0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
294d0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
294e0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
294f0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
29500 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
29510 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
29520 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
29530 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
29540 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
29550 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
29560 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
29570 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
29580 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
29590 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
295a0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
295b0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
295c0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
295d0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
295e0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
295f0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
29600 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
29610 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
29620 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
29630 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
29640 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
29650 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
29660 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
29670 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
29680 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
29690 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
296a0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
296b0 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
296c0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
296d0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
296e0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
296f0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
29700 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
29710 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
29720 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
29730 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
29740 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
29750 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
29760 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
29770 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
29780 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
29790 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
297a0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
297b0 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
297c0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
297d0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
297e0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
297f0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
29800 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
29810 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
29820 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
29830 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
29840 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
29850 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  PI int sqlite3_l
29860 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
29870 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
29880 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
29890 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
298a0 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
298b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
298c0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
298d0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
298e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
298f0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
29900 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
29910 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
29920 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
29930 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
29940 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
29950 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
29960 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
29970 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
29980 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
29990 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
299a0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
299b0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
299c0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
299d0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
299e0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
299f0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
29a00 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
29a10 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
29a20 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29a30 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
29a40 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
29a50 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
29a60 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
29a70 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29a80 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
29a90 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
29aa0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
29ab0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29ac0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
29ad0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
29ae0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
29af0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29b00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
29b10 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
29b20 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
29b30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29b40 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29b50 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
29b60 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
29b70 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
29b80 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
29b90 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
29ba0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
29bb0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
29bc0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
29bd0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
29be0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
29bf0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29c00 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
29c10 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
29c20 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
29c30 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29c40 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
29c50 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
29c60 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
29c70 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
29c80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29c90 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
29ca0 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
29cb0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
29cc0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
29cd0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29ce0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
29cf0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
29d00 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
29d10 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29d20 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
29d30 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
29d40 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
29d50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29d60 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29d70 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
29d80 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
29d90 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
29da0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
29db0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
29dc0 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  t.  If [sqlite3_
29dd0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
29de0 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65  .** the equivale
29df0 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f  nt tries to allo
29e00 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d  cate space for m
29e10 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61  ore than this ma
29e20 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e  ny opcodes.** in
29e30 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72   a single prepar
29e40 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e  ed statement, an
29e50 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72   SQLITE_NOMEM er
29e60 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
29e70 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29e80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
29e90 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
29ea0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
29eb0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
29ec0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29ed0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
29ee0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
29ef0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
29f00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29f10 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
29f20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29f30 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
29f40 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29f50 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
29f60 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
29f70 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
29f80 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
29f90 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
29fa0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
29fb0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29fc0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29fd0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
29fe0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
29ff0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
2a000 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
2a010 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
2a020 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
2a030 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
2a040 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a050 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2a060 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
2a070 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2a080 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
2a090 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a0a0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
2a0b0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
2a0c0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
2a0d0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
2a0e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
2a0f0 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
2a100 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
2a110 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
2a120 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a130 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
2a140 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
2a150 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
2a160 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a170 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2a180 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a190 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
2a1a0 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
2a1b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2a1c0 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
2a1d0 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
2a1e0 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
2a1f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a200 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
2a210 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
2a220 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2a230 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
2a240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a250 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
2a260 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2a270 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
2a280 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2a290 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2a2a0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
2a2b0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2a2c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
2a2d0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
2a2e0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2a2f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
2a300 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
2a310 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
2a320 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
2a330 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
2a340 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
2a350 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
2a360 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
2a370 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
2a380 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2a390 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
2a3a0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
2a3b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a3c0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2a3d0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
2a3e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a3f0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2a400 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
2a410 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a420 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
2a430 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
2a440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a450 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2a460 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
2a470 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a480 20 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a   Prepare Flags.*
2a490 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2a4a0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
2a4b0 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63  ous flags that c
2a4c0 61 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74  an be passed int
2a4d0 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22  o.** "prepFlags"
2a4e0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2a4f0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2a500 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20  re_v3()] and.** 
2a510 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a520 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61  16_v3()] interfa
2a530 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66  ces..**.** New f
2a540 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 65  lags may be adde
2a550 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
2a560 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
2a570 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
2a580 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2a590 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64  ERSISTENT]] ^(<d
2a5a0 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  t>SQLITE_PREPARE
2a5b0 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e  _PERSISTENT</dt>
2a5c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49  .** <dd>The SQLI
2a5d0 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2a5e0 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20  STENT flag is a 
2a5f0 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72  hint to the quer
2a600 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61  y planner.** tha
2a610 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2a620 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2a630 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20   retained for a 
2a640 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a  long time and.**
2a650 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64   probably reused
2a660 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e   many times.)^ ^
2a670 57 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61  Without this fla
2a680 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  g, [sqlite3_prep
2a690 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64  are_v3()].** and
2a6a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a6b0 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65  e16_v3()] assume
2a6c0 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
2a6d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ed statement wil
2a6e0 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75  l .** be used ju
2a6f0 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f  st once or at mo
2a700 73 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61  st a few times a
2a710 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65  nd then destroye
2a720 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2a730 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2a740 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e  relatively soon.
2a750 20 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   The current imp
2a760 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73  lementation acts
2a770 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  .** on this hint
2a780 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65   by avoiding the
2a790 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69   use of [lookasi
2a7a0 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73  de memory] so as
2a7b0 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65   not to.** deple
2a7c0 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73  te the limited s
2a7d0 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  tore of lookasid
2a7e0 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65  e memory. Future
2a7f0 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20   versions of.** 
2a800 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f  SQLite may act o
2a810 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 66  n this hint diff
2a820 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c  erently..** </dl
2a830 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
2a840 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2a850 49 53 54 45 4e 54 20 20 20 20 20 20 20 20 20 20  ISTENT          
2a860 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20      0x01../*.** 
2a870 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
2a880 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
2a890 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
2a8a0 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
2a8b0 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45   compiler}.** ME
2a8c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
2a8d0 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
2a8e0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2a8f0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
2a900 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 74  QL statement, it
2a910 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
2a920 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
2a930 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
2a940 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
2a950 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2a960 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72 20 77    Or, in other w
2a970 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f 75 74  ords, these rout
2a980 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73  ines.** are cons
2a990 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74 68 65  tructors for the
2a9a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a9b0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ment] object..**
2a9c0 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72 72 65  .** The preferre
2a9d0 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75 73 65  d routine to use
2a9e0 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   is [sqlite3_pre
2a9f0 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54 68 65  pare_v2()].  The
2aa00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2aa10 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66 61 63  pare()] interfac
2aa20 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20  e is legacy and 
2aa30 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65  should be avoide
2aa40 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  d..** [sqlite3_p
2aa50 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68 61 73  repare_v3()] has
2aa60 20 61 6e 20 65 78 74 72 61 20 22 70 72 65 70 46   an extra "prepF
2aa70 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74 68 61  lags" option tha
2aa80 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72  t is used.** for
2aa90 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f 73 65   special purpose
2aaa0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65  s..**.** The use
2aab0 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 69 6e   of the UTF-8 in
2aac0 74 65 72 66 61 63 65 73 20 69 73 20 70 72 65 66  terfaces is pref
2aad0 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69 74 65  erred, as SQLite
2aae0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f   currently.** do
2aaf0 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67 20 75  es all parsing u
2ab00 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54 68 65  sing UTF-8.  The
2ab10 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63   UTF-16 interfac
2ab20 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
2ab30 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e 69 65  ** as a convenie
2ab40 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d 31 36  nce.  The UTF-16
2ab50 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b   interfaces work
2ab60 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67 20 74   by converting t
2ab70 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65 78 74  he.** input text
2ab80 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74 68 65   into UTF-8, the
2ab90 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63  n invoking the c
2aba0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55 54 46  orresponding UTF
2abb0 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  -8 interface..**
2abc0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
2abd0 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
2abe0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2abf0 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
2ac00 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
2ac10 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
2ac20 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
2ac30 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2ac40 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
2ac50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2ac60 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
2ac70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
2ac80 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
2ac90 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
2aca0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2acb0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
2acc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
2acd0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
2ace0 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
2acf0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
2ad00 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
2ad10 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c 69 74  prepare(), sqlit
2ad20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c  e3_prepare_v2(),
2ad30 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2ad40 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20  prepare_v3().** 
2ad50 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
2ad60 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
2ad70 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c 20 73  3_prepare16(), s
2ad80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ad90 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71  _v2(),.** and sq
2ada0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2adb0 76 33 28 29 20 75 73 65 20 55 54 46 2d 31 36 2e  v3() use UTF-16.
2adc0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
2add0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
2ade0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2adf0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
2ae00 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
2ae10 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2ae20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f   ^If nByte is po
2ae30 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  sitive, then it 
2ae40 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2ae50 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66   of bytes read f
2ae60 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e  rom zSql.  ^If n
2ae70 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68  Byte is zero, th
2ae80 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a  en no prepared.*
2ae90 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67  * statement is g
2aea0 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20  enerated..** If 
2aeb0 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
2aec0 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
2aed0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
2aee0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
2aef0 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20  n.** there is a 
2af00 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63  small performanc
2af10 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70  e advantage to p
2af20 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
2af30 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
2af40 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2af50 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2af60 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
2af70 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
2af80 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
2af90 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  tor..**.** ^If p
2afa0 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
2afb0 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
2afc0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2afd0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
2afe0 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
2aff0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
2b000 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
2b010 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
2b020 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
2b030 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
2b040 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2b050 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
2b060 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2b070 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
2b080 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
2b090 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
2b0a0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2b0b0 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
2b0c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b0d0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
2b0e0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
2b0f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
2b100 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
2b110 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
2b120 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
2b130 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
2b140 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
2b150 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
2b160 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
2b170 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
2b180 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
2b190 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
2b1a0 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
2b1b0 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
2b1c0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2b1d0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
2b1e0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
2b1f0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2b200 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b210 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
2b220 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2b230 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
2b240 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
2b250 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
2b260 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
2b270 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
2b280 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
2b290 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
2b2a0 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
2b2b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2b2c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2b2d0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2b2e0 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74 65 33  re_v2(), sqlite3
2b2f0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c 20 73  _prepare_v3(), s
2b300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b310 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71  _v2(),.** and sq
2b320 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b330 76 33 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v3() interfaces 
2b340 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  are recommended 
2b350 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
2b360 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64  rams..** The old
2b370 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73  er interfaces (s
2b380 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2b390 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2b3a0 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61 72 65  pare16()).** are
2b3b0 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
2b3c0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
2b3d0 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
2b3e0 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
2b3f0 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
2b400 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "vX" interfaces,
2b410 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2b420 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
2b430 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
2b440 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2b450 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
2b460 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2b470 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
2b480 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
2b490 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2b4a0 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
2b4b0 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
2b4c0 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
2b4d0 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
2b4e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
2b4f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
2b500 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
2b510 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
2b520 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
2b530 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
2b540 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
2b550 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2b560 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
2b570 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
2b580 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
2b590 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
2b5a0 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d  n it again. As m
2b5b0 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d  any as [SQLITE_M
2b5c0 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d  AX_SCHEMA_RETRY]
2b5d0 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c  .** retries will
2b5e0 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71   occur before sq
2b5f0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76  lite3_step() giv
2b600 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e  es up and return
2b610 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c  s an error..** <
2b620 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
2b630 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
2b640 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
2b650 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
2b660 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
2b670 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
2b680 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
2b690 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
2b6a0 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
2b6b0 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
2b6c0 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
2b6d0 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
2b6e0 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
2b6f0 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
2b700 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
2b710 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
2b720 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
2b730 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
2b740 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
2b750 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
2b760 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2b770 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
2b780 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
2b790 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
2b7a0 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
2b7b0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
2b7c0 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
2b7d0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
2b7e0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
2b7f0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
2b800 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
2b810 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
2b820 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
2b830 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
2b840 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
2b850 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
2b860 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
2b870 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
2b880 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
2b890 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
2b8a0 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
2b8b0 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
2b8c0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2b8d0 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
2b8e0 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
2b8f0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
2b900 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
2b910 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2b920 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
2b930 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
2b940 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2b950 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
2b960 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
2b970 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
2b980 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
2b990 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
2b9a0 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
2b9b0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2b9c0 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
2b9d0 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
2b9e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b9f0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
2ba00 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
2ba10 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
2ba20 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
2ba30 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
2ba40 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
2ba50 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
2ba60 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
2ba70 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT3] compile-
2ba80 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
2ba90 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e  nabled..** </li>
2baa0 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74  .**.** <p>^sqlit
2bab0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20  e3_prepare_v3() 
2bac0 64 69 66 66 65 72 73 20 66 72 6f 6d 20 73 71 6c  differs from sql
2bad0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2bae0 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67  ) only in having
2baf0 0a 2a 2a 20 74 68 65 20 65 78 74 72 61 20 70 72  .** the extra pr
2bb00 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65  epFlags paramete
2bb10 72 2c 20 77 68 69 63 68 20 69 73 20 61 20 62 69  r, which is a bi
2bb20 74 20 61 72 72 61 79 20 63 6f 6e 73 69 73 74 69  t array consisti
2bb30 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a  ng of zero or.**
2bb40 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
2bb50 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2bb60 53 49 53 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50  SISTENT|SQLITE_P
2bb70 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e  REPARE_*] flags.
2bb80 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2bb90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 69  3_prepare_v2() i
2bba0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 65  nterface works e
2bbb0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
2bbc0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  as.** sqlite3_pr
2bbd0 65 70 61 72 65 5f 76 33 28 29 20 77 69 74 68 20  epare_v3() with 
2bbe0 61 20 7a 65 72 6f 20 70 72 65 70 46 6c 61 67 73  a zero prepFlags
2bbf0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
2bc00 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  /ol>.*/.SQLITE_A
2bc10 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
2bc20 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
2bc30 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2bc40 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2bc50 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2bc60 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2bc70 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2bc80 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2bc90 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2bca0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2bcb0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2bcc0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2bcd0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2bce0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2bcf0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2bd00 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2bd10 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2bd20 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2bd30 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2bd40 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2bd50 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2bd60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
2bd70 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
2bd80 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2bd90 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2bda0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2bdb0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2bdc0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2bdd0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2bde0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2bdf0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2be00 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2be10 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2be20 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2be30 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2be40 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2be50 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2be60 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2be70 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2be80 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2be90 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2bea0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
2beb0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
2bec0 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c 69  epare_v3(.  sqli
2bed0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2bee0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2bef0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2bf00 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2bf10 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2bf20 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2bf30 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2bf40 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2bf50 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2bf60 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2bf70 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e  tes. */.  unsign
2bf80 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73  ed int prepFlags
2bf90 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72  , /* Zero or mor
2bfa0 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2bfb0 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c  _ flags */.  sql
2bfc0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2bfd0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2bfe0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2bff0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2c000 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2c010 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2c020 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2c030 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
2c040 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2c050 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2c060 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2c070 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2c080 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2c090 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2c0a0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2c0b0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2c0c0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2c0d0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2c0e0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2c0f0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2c100 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2c110 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2c120 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2c130 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2c140 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2c150 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2c160 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2c170 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2c180 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
2c190 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c1a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c1b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2c1c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2c1d0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2c1e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2c1f0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2c200 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2c210 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2c220 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2c230 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2c240 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2c250 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2c260 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2c270 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2c280 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2c290 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2c2a0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2c2b0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2c2c0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2c2d0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2c2e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2c2f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c300 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2c310 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2c320 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2c330 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2c340 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2c350 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2c360 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2c370 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2c380 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c390 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2c3a0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2c3b0 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69   */.  unsigned i
2c3c0 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a  nt prepFlags, /*
2c3d0 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51   Zero or more SQ
2c3e0 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c  LITE_PREPARE_ fl
2c3f0 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  ags */.  sqlite3
2c400 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2c410 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2c420 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2c430 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2c440 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2c450 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2c460 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2c470 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2c480 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2c490 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2c4a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c4b0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c4c0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2c4d0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2c4e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2c4f0 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2c500 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2c510 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2c520 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c530 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2c540 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b  .** created by [
2c550 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c560 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
2c570 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a  prepare_v3()],.*
2c580 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c590 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
2c5a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c5b0 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  6_v3()]..** ^The
2c5c0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2c5d0 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  d_sql(P) interfa
2c5e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2c5f0 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a  nter to a UTF-8.
2c600 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
2c610 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78  ning the SQL tex
2c620 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74  t of prepared st
2c630 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a  atement P with.*
2c640 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  * [bound paramet
2c650 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a  ers] expanded..*
2c660 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2c670 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65  le, if a prepare
2c680 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
2c690 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
2c6a0 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45   SQL.** text "SE
2c6b0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2c6c0 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72  and if parameter
2c6d0 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74   $abc is bound t
2c6e0 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a  o integer 2345.*
2c6f0 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * and parameter 
2c700 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c  :xyz is unbound,
2c710 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71   then sqlite3_sq
2c720 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  l() will return.
2c730 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
2c740 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20  string, "SELECT 
2c750 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73  $abc,:xyz" but s
2c760 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2c770 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  sql().** will re
2c780 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34  turn "SELECT 234
2c790 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a  5,NULL".)^.**.**
2c7a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2c7b0 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74  panded_sql() int
2c7c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e  erface returns N
2c7d0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
2c7e0 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73  ent memory.** is
2c7f0 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f   available to ho
2c800 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f  ld the result, o
2c810 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20  r if the result 
2c820 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
2c830 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  .** the maximum 
2c840 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65  string length de
2c850 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2c860 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2c870 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  NGTH]..**.** ^Th
2c880 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
2c890 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
2c8a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2c8b0 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20  limits the size 
2c8c0 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61  of.** bound para
2c8d0 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73  meter expansions
2c8e0 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
2c8f0 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70  OMIT_TRACE] comp
2c900 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
2c910 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65  on causes sqlite
2c920 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2c930 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72   to always retur
2c940 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  n NULL..**.** ^T
2c950 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2c960 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71  ed by sqlite3_sq
2c970 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20  l(P) is managed 
2c980 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73  by SQLite and is
2c990 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
2c9a0 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65  y freed when the
2c9b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2c9c0 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2c9d0 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67  ..** ^The string
2c9e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2c9f0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2ca00 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68  l(P), on the oth
2ca10 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f  er hand,.** is o
2ca20 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2ca30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2ca40 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65  and must be free
2ca50 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2ca60 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e  ion.** by passin
2ca70 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
2ca80 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  _free()]..*/.SQL
2ca90 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2caa0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
2cab0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2cac0 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  tmt);.SQLITE_API
2cad0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
2cae0 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69  xpanded_sql(sqli
2caf0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2cb00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cb10 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2cb20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2cb30 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
2cb40 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
2cb50 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2cb60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cb70 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
2cb80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2cb90 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2cba0 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
2cbb0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
2cbc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
2cbd0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
2cbe0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
2cbf0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2cc00 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
2cc10 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2cc20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2cc30 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2cc40 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
2cc50 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
2cc60 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2cc70 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
2cc80 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
2cc90 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
2cca0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
2ccb0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
2ccc0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
2ccd0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
2cce0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
2ccf0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
2cd00 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
2cd10 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
2cd20 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2cd30 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
2cd40 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
2cd50 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2cd60 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
2cd70 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
2cd80 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
2cd90 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
2cda0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2cdb0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
2cdc0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2cdd0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
2cde0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2cdf0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
2ce00 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
2ce10 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
2ce20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
2ce30 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
2ce40 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
2ce50 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
2ce60 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
2ce70 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
2ce80 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
2ce90 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
2cea0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
2ceb0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2cec0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
2ced0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
2cee0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
2cef0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
2cf00 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2cf10 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
2cf20 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
2cf30 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
2cf40 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
2cf50 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
2cf60 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
2cf70 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
2cf80 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
2cf90 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
2cfa0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2cfb0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2cfc0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
2cfd0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
2cfe0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
2cff0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
2d000 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
2d010 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
2d020 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
2d030 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
2d040 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2d050 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
2d060 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20  n disk..** ^The 
2d070 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2d080 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63  donly() interfac
2d090 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66  e returns true f
2d0a0 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65  or [BEGIN] since
2d0b0 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65  .** [BEGIN] mere
2d0c0 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c  ly sets internal
2d0d0 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20   flags, but the 
2d0e0 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d  [BEGIN|BEGIN IMM
2d0f0 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b  EDIATE] and.** [
2d100 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c  BEGIN|BEGIN EXCL
2d110 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20  USIVE] commands 
2d120 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74  do touch the dat
2d130 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20  abase and so.** 
2d140 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2d150 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20  donly() returns 
2d160 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20  false for those 
2d170 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 53 51 4c  commands..*/.SQL
2d180 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2d190 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2d1a0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
2d1b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2d1c0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2d1d0 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
2d1e0 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
2d1f0 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54  een Reset.** MET
2d200 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2d210 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2d220 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2d230 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2d240 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2d250 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
2d260 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d270 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
2d280 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
2d290 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
2d2a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2d2b0 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20  but has neither 
2d2c0 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
2d2d0 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  n (returned.** [
2d2e0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f  SQLITE_DONE] fro
2d2f0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  m [sqlite3_step(
2d300 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e  S)]) nor.** been
2d310 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
2d320 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
2d330 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
2d340 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
2d350 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d360 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
2d370 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
2d380 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
2d390 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
2d3a0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
2d3b0 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
2d3c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d3d0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
2d3e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2d3f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2d400 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
2d410 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
2d420 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
2d430 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
2d440 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
2d450 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
2d460 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
2d470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d480 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
2d490 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
2d4a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
2d4b0 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
2d4c0 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
2d4d0 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
2d4e0 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
2d4f0 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
2d500 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
2d510 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
2d520 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
2d530 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
2d540 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
2d550 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
2d560 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d   int sqlite3_stm
2d570 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
2d580 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2d590 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
2d5a0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
2d5b0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
2d5c0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
2d5d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
2d5e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2d5f0 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
2d600 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
2d610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2d620 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
2d630 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
2d640 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
2d650 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
2d660 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
2d670 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
2d680 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
2d690 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
2d6a0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
2d6b0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
2d6c0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
2d6d0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
2d6e0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2d6f0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
2d700 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
2d710 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
2d720 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
2d730 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
2d740 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
2d750 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
2d760 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
2d770 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
2d780 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
2d790 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
2d7a0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
2d7b0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
2d7c0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
2d7d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d7e0 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
2d7f0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
2d800 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
2d810 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
2d820 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
2d830 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
2d840 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
2d850 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68  lite3_value.  Th
2d860 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  e.** [sqlite3_va
2d870 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72  lue_dup()] inter
2d880 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2d890 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20   to construct a 
2d8a0 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65  new .** protecte
2d8b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2d8c0 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63  from an unprotec
2d8d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d8e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
2d8f0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
2d900 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
2d910 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
2d920 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
2d930 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
2d940 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
2d950 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
2d960 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2d970 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2d980 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
2d990 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
2d9a0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2d9b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
2d9c0 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
2d9d0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
2d9e0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
2d9f0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
2da00 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
2da10 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
2da20 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
2da30 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
2da40 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
2da50 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
2da60 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
2da70 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
2da80 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
2da90 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2daa0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
2dab0 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
2dac0 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
2dad0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
2dae0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
2daf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2db00 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
2db10 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
2db20 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
2db30 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
2db40 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
2db50 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
2db60 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
2db70 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
2db80 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
2db90 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2dba0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2dbb0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2dbc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2dbd0 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
2dbe0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
2dbf0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
2dc00 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2dc10 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
2dc20 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
2dc30 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
2dc40 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
2dc50 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
2dc60 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2dc70 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
2dc80 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
2dc90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2dca0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2dcb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2dcc0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2dcd0 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
2dce0 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
2dcf0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2dd00 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
2dd10 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
2dd20 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2dd30 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2dd40 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
2dd50 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
2dd60 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
2dd70 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2dd80 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
2dd90 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
2dda0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
2ddb0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2ddc0 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
2ddd0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 61  truct sqlite3_va
2dde0 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  lue sqlite3_valu
2ddf0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
2de00 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
2de10 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
2de20 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
2de30 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
2de40 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
2de50 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
2de60 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
2de70 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
2de80 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
2de90 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2dea0 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
2deb0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
2dec0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
2ded0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2dee0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2def0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
2df00 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2df10 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2df20 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
2df30 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
2df40 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
2df50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2df60 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
2df70 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
2df80 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2df90 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
2dfa0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2dfb0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
2dfc0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2dfd0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
2dfe0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
2dff0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
2e000 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2e010 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
2e020 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
2e030 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
2e040 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
2e050 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
2e060 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
2e070 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
2e080 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
2e090 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
2e0a0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
2e0b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2e0c0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
2e0d0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
2e0e0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
2e0f0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
2e100 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ding}.** METHOD:
2e110 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e120 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
2e130 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2e140 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
2e150 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2e160 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
2e170 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
2e180 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
2e190 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
2e1a0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
2e1b0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
2e1c0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
2e1d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
2e1e0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
2e1f0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
2e200 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
2e210 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
2e220 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
2e230 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
2e240 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
2e250 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
2e260 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
2e270 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
2e280 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
2e290 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
2e2a0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
2e2b0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
2e2c0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
2e2d0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
2e2e0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
2e2f0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
2e300 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
2e310 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2e320 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
2e330 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
2e340 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2e350 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2e360 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
2e370 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
2e380 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
2e390 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2e3a0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
2e3b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2e3c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
2e3d0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
2e3e0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
2e3f0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2e400 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
2e410 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
2e420 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
2e430 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
2e440 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2e450 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
2e460 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
2e470 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
2e480 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
2e490 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
2e4a0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
2e4b0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
2e4c0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
2e4d0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
2e4e0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
2e4f0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
2e500 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
2e510 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
2e520 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2e530 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e540 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
2e550 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
2e560 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
2e570 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
2e580 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
2e590 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
2e5a0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
2e5b0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
2e5c0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
2e5d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
2e5e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2e5f0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
2e600 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
2e610 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
2e620 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2e630 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
2e640 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
2e650 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
2e660 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2e670 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2e680 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2e690 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2e6a0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2e6b0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
2e6c0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
2e6d0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2e6e0 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
2e6f0 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
2e700 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
2e710 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
2e720 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
2e730 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
2e740 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
2e750 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2e760 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
2e770 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2e780 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
2e790 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
2e7a0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
2e7b0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2e7c0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
2e7d0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
2e7e0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2e7f0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
2e800 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
2e810 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2e820 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2e830 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2e840 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
2e850 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
2e860 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2e870 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
2e880 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2e890 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
2e8a0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2e8b0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
2e8c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2e8d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2e8e0 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
2e8f0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
2e900 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2e910 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
2e920 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
2e930 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
2e940 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
2e950 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
2e960 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2e970 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c  _text16() or sql
2e980 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2e990 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20  () then.** that 
2e9a0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2e9b0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
2e9c0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
2e9d0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
2e9e0 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
2e9f0 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
2ea00 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
2ea10 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
2ea20 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
2ea30 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
2ea40 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
2ea50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2ea60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2ea70 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
2ea80 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
2ea90 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
2eaa0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
2eab0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
2eac0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
2ead0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
2eae0 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
2eaf0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
2eb00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
2eb10 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
2eb20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72  the BLOB and str
2eb30 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65  ing binding inte
2eb40 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64  rfaces.** is a d
2eb50 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
2eb60 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2eb70 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
2eb80 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
2eb90 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2eba0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
2ebb0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2ebc0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
2ebd0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
2ebe0 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
2ebf0 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50   call to bind AP
2ec00 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20  I fails..** ^If 
2ec10 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2ec20 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
2ec30 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
2ec40 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
2ec50 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
2ec60 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
2ec70 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
2ec80 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
2ec90 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2eca0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
2ecb0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
2ecc0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
2ecd0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
2ece0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
2ecf0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
2ed00 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
2ed10 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2ed20 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
2ed30 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
2ed40 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2ed50 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2ed60 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2ed70 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
2ed80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2ed90 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
2eda0 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
2edb0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
2edc0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
2edd0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
2ede0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
2edf0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
2ee00 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
2ee10 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
2ee20 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
2ee30 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
2ee40 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2ee50 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2ee60 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
2ee70 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
2ee80 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
2ee90 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
2eea0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2eeb0 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
2eec0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
2eed0 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
2eee0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
2eef0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
2ef00 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2ef10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ef20 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2ef30 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
2ef40 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
2ef50 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
2ef60 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
2ef70 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
2ef80 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
2ef90 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
2efa0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
2efb0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
2efc0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
2efd0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
2efe0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
2eff0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
2f000 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
2f010 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
2f020 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
2f030 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
2f040 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2f050 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
2f060 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
2f070 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
2f080 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
2f090 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
2f0a0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
2f0b0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2f0c0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  B..**.** ^The sq
2f0d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74  lite3_bind_point
2f0e0 65 72 28 53 2c 49 2c 50 2c 54 29 20 72 6f 75 74  er(S,I,P,T) rout
2f0f0 69 6e 65 20 63 61 75 73 65 73 20 74 68 65 20 49  ine causes the I
2f100 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e  -th parameter in
2f110 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2f120 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 68 61  atement] S to ha
2f130 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75 65 20  ve an SQL value 
2f140 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74 6f 20  of NULL, but to 
2f150 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73 6f 63  also be.** assoc
2f160 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
2f170 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79 70 65  ointer P of type
2f180 20 54 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   T..** ^The sqli
2f190 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
2f1a0 28 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  () routine can b
2f1b0 65 20 75 73 65 64 20 74 6f 20 70 61 73 73 0a 2a  e used to pass.*
2f1c0 2a 20 68 6f 73 74 2d 6c 61 6e 67 75 61 67 65 20  * host-language 
2f1d0 70 6f 69 6e 74 65 72 73 20 69 6e 74 6f 20 5b 61  pointers into [a
2f1e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f1f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2f200 5d 2e 0a 2a 2a 20 5e 41 20 70 61 72 61 6d 65 74  ]..** ^A paramet
2f210 65 72 20 74 68 61 74 20 69 73 20 69 6e 69 74 69  er that is initi
2f220 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
2f230 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74  lite3_bind_point
2f240 65 72 28 29 5d 20 61 70 70 65 61 72 73 0a 2a 2a  er()] appears.**
2f250 20 74 6f 20 62 65 20 61 6e 20 6f 72 64 69 6e 61   to be an ordina
2f260 72 79 20 53 51 4c 20 4e 55 4c 4c 20 76 61 6c 75  ry SQL NULL valu
2f270 65 20 74 6f 20 65 76 65 72 79 74 68 69 6e 67 20  e to everything 
2f280 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 5b 73  other than.** [s
2f290 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 70 6f 69  qlite3_value_poi
2f2a0 6e 74 65 72 28 29 5d 2e 20 20 54 68 65 20 54 20  nter()].  The T 
2f2b0 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
2f2c0 20 62 65 20 61 20 73 74 61 74 69 63 20 73 74 72   be a static str
2f2d0 69 6e 67 2c 0a 2a 2a 20 70 72 65 66 65 72 61 62  ing,.** preferab
2f2e0 6c 79 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  ly a string lite
2f2f0 72 61 6c 2e 20 20 54 68 65 20 70 72 6f 63 65 64  ral.  The proced
2f300 75 72 65 20 74 68 61 74 20 69 6e 76 6f 6b 65 73  ure that invokes
2f310 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e   .** sqlite3_bin
2f320 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c  d_pointer(S,I,P,
2f330 54 29 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  T) continues to 
2f340 6f 77 6e 20 74 68 65 20 50 20 61 6e 64 20 54 20  own the P and T 
2f350 70 6f 69 6e 74 65 72 73 20 61 6e 64 0a 2a 2a 20  pointers and.** 
2f360 6d 75 73 74 20 67 75 61 72 61 6e 74 65 65 20 74  must guarantee t
2f370 68 61 74 20 74 68 6f 73 65 20 70 6f 69 6e 74 65  hat those pointe
2f380 72 73 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 20  rs remain valid 
2f390 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20  until after the 
2f3a0 6c 61 73 74 0a 2a 2a 20 61 63 63 65 73 73 20 76  last.** access v
2f3b0 69 61 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ia [sqlite3_valu
2f3c0 65 5f 70 6f 69 6e 74 65 72 28 29 5d 2e 20 20 54  e_pointer()].  T
2f3d0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f3e0 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 74 69 6e  pointer() routin
2f3f0 65 0a 2a 2a 20 69 73 20 70 61 72 74 20 6f 66 20  e.** is part of 
2f400 74 68 65 20 5b 70 6f 69 6e 74 65 72 20 70 61 73  the [pointer pas
2f410 73 69 6e 67 20 69 6e 74 65 72 66 61 63 65 5d 20  sing interface] 
2f420 61 64 64 65 64 20 66 6f 72 20 53 51 4c 69 74 65  added for SQLite
2f430 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e   3.20.0..**.** ^
2f440 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
2f450 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2f460 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2f470 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
2f480 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
2f490 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f4a0 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
2f4b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2f4c0 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
2f4d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2f4e0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
2f4f0 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
2f500 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
2f510 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
2f520 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
2f530 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
2f540 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
2f550 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
2f560 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
2f570 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
2f580 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2f590 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2f5a0 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
2f5b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2f5c0 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
2f5d0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
2f5e0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
2f5f0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
2f600 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
2f610 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
2f620 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
2f630 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
2f640 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2f650 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
2f660 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2f670 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2f680 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
2f690 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
2f6a0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
2f6b0 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
2f6c0 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62  _TOOBIG] might b
2f6d0 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
2f6e0 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69  e size of a stri
2f6f0 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78  ng or BLOB.** ex
2f700 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70  ceeds limits imp
2f710 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
2f720 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2f730 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f  LIMIT_LENGTH]) o
2f740 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  r.** [SQLITE_MAX
2f750 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53  _LENGTH]..** ^[S
2f760 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
2f770 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2f780 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
2f790 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2f7a0 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
2f7b0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
2f7c0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
2f7d0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
2f7e0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2f7f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2f800 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2f810 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2f820 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
2f830 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2f840 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2f850 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2f860 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2f870 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2f880 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2f890 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
2f8a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
2f8b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2f8c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28  te3_bind_blob64(
2f8d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f8e0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2f8f0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2f900 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2f910 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2f920 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2f930 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2f940 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
2f950 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2f960 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45   double);.SQLITE
2f970 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2f980 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
2f990 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2f9a0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
2f9b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2f9c0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2f9d0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2f9e0 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  3_int64);.SQLITE
2f9f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2fa00 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
2fa10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2fa20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2fa30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2fa40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2fa50 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69  nt,const char*,i
2fa60 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2fa70 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2fa80 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2fa90 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2faa0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2fab0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2fac0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2fad0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2fae0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2faf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fb00 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
2fb10 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2fb20 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2fb30 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2fb40 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67  *)(void*), unsig
2fb50 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e  ned char encodin
2fb60 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  g);.SQLITE_API i
2fb70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2fb80 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2fb90 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2fba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2fbb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2fbc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
2fbd0 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d  nter(sqlite3_stm
2fbe0 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20  t*, int, void*, 
2fbf0 63 6f 6e 73 74 20 63 68 61 72 2a 29 3b 0a 53 51  const char*);.SQ
2fc00 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2fc10 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2fc20 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2fc30 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53  , int, int n);.S
2fc40 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2fc50 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2fc60 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2fc70 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2fc80 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  3_uint64);../*.*
2fc90 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2fca0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
2fcb0 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ters.** METHOD: 
2fcc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2fcd0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
2fce0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2fcf0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
2fd00 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
2fd10 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
2fd20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fd30 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
2fd40 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
2fd50 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
2fd60 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
2fd70 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
2fd80 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
2fd90 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
2fda0 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
2fdb0 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
2fdc0 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
2fdd0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
2fde0 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
2fdf0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
2fe00 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
2fe10 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
2fe20 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
2fe30 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
2fe40 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
2fe50 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
2fe60 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
2fe70 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
2fe80 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
2fe90 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
2fea0 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
2feb0 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
2fec0 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
2fed0 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
2fee0 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
2fef0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
2ff00 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2ff10 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2ff20 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2ff30 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ff40 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2ff50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2ff60 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2ff70 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2ff80 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2ff90 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2ffa0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2ffb0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2ffc0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
2ffd0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
2ffe0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2fff0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
30000 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
30010 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
30020 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
30030 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
30040 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
30050 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
30060 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
30070 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
30080 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
30090 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
300a0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
300b0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
300c0 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
300d0 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
300e0 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
300f0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
30100 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
30110 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
30120 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
30130 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
30140 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
30150 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
30160 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
30170 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
30180 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
30190 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
301a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
301b0 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
301c0 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
301d0 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
301e0 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
301f0 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
30200 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
30210 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
30220 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
30230 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
30240 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
30250 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
30260 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
30270 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
30280 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
30290 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
302a0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
302b0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
302c0 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
302d0 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
302e0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
302f0 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
30300 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
30310 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
30320 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
30330 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
30340 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72  pare16_v2()], or
30350 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30360 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v3()]..**.**
30370 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
30380 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
30390 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
303a0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
303b0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
303c0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
303d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
303e0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
303f0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
30400 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
30410 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
30420 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
30430 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
30440 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
30450 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
30460 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
30470 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30480 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
30490 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
304a0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
304b0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
304c0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
304d0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
304e0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
304f0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
30500 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
30510 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
30520 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
30530 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
30540 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
30550 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
30560 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
30570 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
30580 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
30590 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
305a0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
305b0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
305c0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
305d0 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
305e0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
305f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
30600 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
30610 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e  prepare16_v3()].
30620 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
30630 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
30640 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
30650 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
30660 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30670 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
30680 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30690 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
306a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
306b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
306c0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
306d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
306e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
306f0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
30700 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
30710 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
30720 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
30730 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30740 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43  e3_stmt.**.** ^C
30750 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
30760 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
30770 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
30780 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
30790 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
307a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
307b0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
307c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
307d0 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
307e0 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
307f0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
30800 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
30810 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
30820 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
30830 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
30840 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
30850 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
30860 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
30870 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
30880 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30890 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
308a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
308b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
308c0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
308d0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
308e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
308f0 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69  . ^If this routi
30900 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ne returns 0, th
30910 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a  at means the .**
30920 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30930 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f  ment] returns no
30940 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
30950 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
30960 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75  .** ^However, ju
30970 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73 20  st because this 
30980 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30990 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65  a positive numbe
309a0 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65  r does not.** me
309b0 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d  an that one or m
309c0 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61  ore rows of data
309d0 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
309e0 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74  d.  ^A SELECT st
309f0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20  atement.** will 
30a00 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 6f  always have a po
30a10 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63  sitive sqlite3_c
30a20 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75  olumn_count() bu
30a30 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  t depending on t
30a40 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  he.** WHERE clau
30a50 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  se constraints a
30a60 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e  nd the table con
30a70 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72  tent, it might r
30a80 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a  eturn no rows..*
30a90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
30aa0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
30ab0 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
30ac0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
30ad0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
30ae0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
30af0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30b00 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
30b10 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
30b20 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
30b30 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30b40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
30b50 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
30b60 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
30b70 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
30b80 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
30b90 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
30ba0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
30bb0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
30bc0 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
30bd0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
30be0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
30bf0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
30c00 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
30c10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30c20 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
30c30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
30c40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
30c50 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
30c60 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
30c70 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
30c80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30c90 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
30ca0 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
30cb0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
30cc0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
30cd0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
30ce0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
30cf0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
30d00 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
30d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
30d20 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
30d30 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
30d40 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
30d50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30d60 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
30d70 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
30d80 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
30d90 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
30da0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
30db0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
30dc0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
30dd0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
30de0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
30df0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
30e00 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
30e10 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
30e20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
30e30 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
30e40 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
30e50 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
30e60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
30e70 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
30e80 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
30e90 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
30ea0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
30eb0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
30ec0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
30ed0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
30ee0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
30ef0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
30f00 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
30f10 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
30f20 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
30f30 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
30f40 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
30f50 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
30f60 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
30f70 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
30f80 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
30f90 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
30fa0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
30fb0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
30fc0 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
30fd0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
30fe0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
30ff0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51   the next..*/.SQ
31000 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
31010 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
31020 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
31030 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
31040 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
31050 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
31060 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
31070 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31080 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
31090 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
310a0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
310b0 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
310c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
310d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
310e0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
310f0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
31100 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
31110 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
31120 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
31130 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
31140 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
31150 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
31160 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
31170 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
31180 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
31190 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
311a0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
311b0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
311c0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
311d0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
311e0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
311f0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
31200 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
31210 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
31220 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
31230 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
31240 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
31250 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
31260 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
31270 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
31280 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
31290 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
312a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
312b0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
312c0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
312d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
312e0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
312f0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
31300 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
31310 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
31320 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
31330 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
31340 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
31350 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
31360 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
31370 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
31380 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
31390 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
313a0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
313b0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
313c0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
313d0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
313e0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
313f0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
31400 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
31410 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
31420 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
31430 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
31440 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
31450 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
31460 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
31470 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
31480 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
31490 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
314a0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
314b0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
314c0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
314d0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
314e0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
314f0 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
31500 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
31510 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
31520 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
31530 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
31540 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
31550 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
31560 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
31570 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
31580 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
31590 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
315a0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
315b0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
315c0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
315d0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
315e0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
315f0 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
31600 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
31610 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
31620 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
31630 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
31640 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
31650 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
31660 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
31670 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
31680 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
31690 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
316a0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
316b0 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
316c0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
316d0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
316e0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
316f0 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
31700 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
31710 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
31720 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
31730 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
31740 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
31750 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
31760 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
31770 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
31780 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
31790 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
317a0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
317b0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
317c0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
317d0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
317e0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
317f0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
31800 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
31810 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
31820 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
31830 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
31840 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
31850 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
31860 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
31870 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
31880 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
31890 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
318a0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
318b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
318c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
318d0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
318e0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
318f0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
31900 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
31910 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
31920 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
31930 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
31940 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
31950 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
31960 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
31970 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
31980 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
31990 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
319a0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
319b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
319c0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
319d0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
319e0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
319f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
31a00 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
31a10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
31a20 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
31a30 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
31a40 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
31a50 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
31a60 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
31a70 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
31a80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31a90 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
31aa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
31ab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31ac0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
31ad0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
31ae0 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
31af0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31b00 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
31b10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
31b20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31b30 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
31b40 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
31b50 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
31b60 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
31b70 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
31b80 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
31b90 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
31ba0 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
31bb0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
31bc0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
31bd0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
31be0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
31bf0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
31c00 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
31c10 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
31c20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
31c30 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
31c40 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
31c50 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
31c60 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
31c70 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
31c80 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
31c90 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
31ca0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
31cb0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
31cc0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
31cd0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
31ce0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
31cf0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
31d00 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
31d10 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
31d20 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
31d30 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
31d40 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
31d50 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
31d60 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
31d70 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
31d80 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
31d90 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
31da0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
31db0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
31dc0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
31dd0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
31de0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
31df0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
31e00 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
31e10 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
31e20 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
31e30 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
31e40 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
31e50 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
31e60 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
31e70 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
31e80 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
31e90 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
31ea0 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
31eb0 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
31ec0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
31ed0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
31ee0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
31ef0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
31f00 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
31f10 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
31f20 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
31f30 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
31f40 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
31f50 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  alues..*/.SQLITE
31f60 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
31f70 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31f80 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
31f90 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
31fa0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
31fb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
31fc0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
31fd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
31fe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31ff0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
32000 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
32010 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
32020 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  stmt.**.** After
32030 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
32040 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
32050 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
32060 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  any of.** [sqlit
32070 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
32080 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
32090 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v3()], [sqlit
320a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
320b0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
320c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
320d0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
320e0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
320f0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
32100 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
32110 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
32120 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
32130 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
32140 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
32150 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
32160 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
32170 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
32180 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
32190 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
321a0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
321b0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
321c0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
321d0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
321e0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
321f0 65 72 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  er "vX" interfac
32200 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  es.** [sqlite3_p
32210 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
32220 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
32230 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
32240 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a  repare16_v3()],.
32250 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
32260 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
32270 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
32280 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
32290 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
322a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
322b0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
322c0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
322d0 6e 65 77 20 22 76 58 22 20 69 6e 74 65 72 66 61  new "vX" interfa
322e0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
322f0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
32300 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
32310 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
32320 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
32330 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
32340 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
32350 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
32360 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
32370 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
32380 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
32390 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
323a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
323b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
323c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
323d0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
323e0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
323f0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
32400 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
32410 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
32420 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
32430 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
32440 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
32450 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
32460 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
32470 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
32480 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
32490 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
324a0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
324b0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
324c0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
324d0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
324e0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
324f0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
32500 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
32510 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
32520 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
32530 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
32540 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
32550 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
32560 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
32570 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
32580 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
32590 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
325a0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
325b0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
325c0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
325d0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
325e0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
325f0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
32600 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
32610 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
32620 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
32630 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
32640 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
32650 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
32660 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
32670 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
32680 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
32690 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
326a0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
326b0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
326c0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
326d0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
326e0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
326f0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
32700 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
32710 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
32720 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
32730 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
32740 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
32750 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
32760 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
32770 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
32780 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
32790 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
327a0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
327b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
327c0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
327d0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
327e0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
327f0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
32800 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
32810 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
32820 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
32830 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
32840 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
32850 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
32860 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
32870 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
32880 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
32890 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
328a0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
328b0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
328c0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
328d0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
328e0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
328f0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
32900 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
32910 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
32920 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
32930 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
32940 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
32950 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
32960 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
32970 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
32980 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
32990 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
329a0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
329b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
329c0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
329d0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
329e0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
329f0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
32a00 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
32a10 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
32a20 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
32a30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
32a40 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
32a50 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
32a60 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
32a70 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
32a80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
32a90 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
32aa0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
32ab0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
32ac0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
32ad0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
32ae0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
32af0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
32b00 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
32b10 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
32b20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
32b30 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
32b40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
32b50 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
32b60 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
32b70 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
32b80 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
32b90 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
32ba0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
32bb0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
32bc0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
32bd0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
32be0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32bf0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
32c00 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
32c10 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
32c20 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
32c30 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
32c40 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
32c50 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
32c60 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
32c70 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
32c80 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
32c90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
32ca0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
32cb0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
32cc0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
32cd0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
32ce0 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
32cf0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
32d00 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e  t after [version
32d10 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74   3.6.23.1] ([dat
32d20 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a  eof:3.6.23.1],.*
32d30 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
32d40 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
32d50 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
32d60 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
32d70 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
32d80 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
32d90 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
32da0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
32db0 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
32dc0 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
32dd0 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
32de0 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
32df0 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
32e00 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
32e10 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
32e20 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
32e30 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
32e40 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
32e50 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
32e60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
32e70 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
32e80 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
32e90 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
32ea0 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
32eb0 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
32ec0 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
32ed0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
32ee0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
32ef0 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
32f00 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
32f10 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
32f20 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
32f30 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
32f40 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
32f50 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
32f60 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
32f70 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
32f80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
32f90 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
32fa0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
32fb0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
32fc0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
32fd0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
32fe0 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
32ff0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
33000 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
33010 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
33020 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
33030 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
33040 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
33050 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
33060 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
33070 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
33080 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
33090 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
330a0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
330b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
330c0 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20  are_v2()].** or 
330d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
330e0 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  16_v2()] or [sql
330f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
33100 33 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  3()] instead.** 
33110 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
33120 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
33130 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
33140 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
33150 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
33160 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
33170 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
33180 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
33190 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
331a0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
331b0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 58 22   use of the "vX"
331c0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 72   interfaces is r
331d0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53  ecommended..*/.S
331e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
331f0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
33200 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
33210 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
33220 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
33230 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
33240 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33250 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
33260 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
33270 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
33280 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
33290 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
332a0 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
332b0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
332c0 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
332d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
332e0 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
332f0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
33300 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
33310 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
33320 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
33330 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
33340 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
33350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
33360 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
33370 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
33380 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
33390 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
333a0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
333b0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
333c0 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
333d0 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
333e0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
333f0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
33400 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
33410 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
33420 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
33430 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
33440 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
33450 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
33460 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
33470 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
33480 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
33490 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
334a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
334b0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
334c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
334d0 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
334e0 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
334f0 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
33500 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
33510 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
33520 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
33530 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
33540 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
33550 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
33560 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
33570 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
33580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
33590 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
335a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
335b0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
335c0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
335d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
335e0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
335f0 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
33600 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
33610 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
33620 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
33630 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
33640 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
33650 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
33660 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
33670 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
33680 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
33690 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
336a0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
336b0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
336c0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
336d0 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
336e0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
336f0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
33700 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
33710 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
33720 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
33730 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
33740 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
33750 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
33760 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
33770 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
33780 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
33790 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
337a0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
337b0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
337c0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
337d0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
337e0 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
337f0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
33800 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
33810 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
33820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
33830 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
33840 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
33850 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
33860 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
33870 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
33880 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
33890 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
338a0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
338b0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
338c0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
338d0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
338e0 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
338f0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
33900 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
33910 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
33920 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
33930 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
33940 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61  t.**.** <b>Summa
33950 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63  ry:</b>.** <bloc
33960 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f  kquote><table bo
33970 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69  rder=0 cellpaddi
33980 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67  ng=0 cellspacing
33990 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  =0>.** <tr><td><
339a0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
339b0 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61  _blob</b><td>&ra
339c0 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75  rr;<td>BLOB resu
339d0 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
339e0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
339f0 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72  double</b><td>&r
33a00 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73  arr;<td>REAL res
33a10 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
33a20 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
33a30 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  _int</b><td>&rar
33a40 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54  r;<td>32-bit INT
33a50 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  EGER result.** <
33a60 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
33a70 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f  3_column_int64</
33a80 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
33a90 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72  64-bit INTEGER r
33aa0 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
33ab0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
33ac0 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26  mn_text</b><td>&
33ad0 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54  rarr;<td>UTF-8 T
33ae0 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  EXT result.** <t
33af0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
33b00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f  _column_text16</
33b10 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
33b20 55 54 46 2d 31 36 20 54 45 58 54 20 72 65 73 75  UTF-16 TEXT resu
33b30 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
33b40 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
33b50 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61  value</b><td>&ra
33b60 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c  rr;<td>The resul
33b70 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c  t as an .** [sql
33b80 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f  ite3_value|unpro
33b90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33ba0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  alue] object..**
33bb0 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c   <tr><td>&nbsp;<
33bc0 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62  td>&nbsp;<td>&nb
33bd0 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  sp;.** <tr><td><
33be0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
33bf0 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72  _bytes</b><td>&r
33c00 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20  arr;<td>Size of 
33c10 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55  a BLOB.** or a U
33c20 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74  TF-8 TEXT result
33c30 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72   in bytes.** <tr
33c40 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
33c50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e  column_bytes16&n
33c60 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a  bsp;&nbsp;</b>.*
33c70 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73  * <td>&rarr;&nbs
33c80 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65  p;&nbsp;<td>Size
33c90 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45   of UTF-16.** TE
33ca0 58 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c  XT in bytes.** <
33cb0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
33cc0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62  3_column_type</b
33cd0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44  ><td>&rarr;<td>D
33ce0 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79  efault.** dataty
33cf0 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  pe of the result
33d00 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c  .** </table></bl
33d10 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
33d20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a  <b>Details:</b>.
33d30 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
33d40 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
33d50 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
33d60 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
33d70 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
33d80 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
33d90 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
33da0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
33db0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
33dc0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
33dd0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
33de0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
33df0 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
33e00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
33e10 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
33e20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
33e30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
33e40 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
33e50 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
33e60 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
33e70 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
33e80 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
33e90 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
33ea0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
33eb0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
33ec0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
33ed0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
33ee0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
33ef0 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
33f00 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
33f10 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
33f20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
33f30 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
33f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
33f50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
33f60 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
33f70 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
33f80 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
33f90 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
33fa0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
33fb0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
33fc0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
33fd0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
33fe0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
33ff0 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
34000 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
34010 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
34020 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
34030 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
34040 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
34050 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
34060 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
34070 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
34080 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
34090 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
340a0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
340b0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
340c0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
340d0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
340e0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
340f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
34100 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
34110 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
34120 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
34130 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
34140 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
34150 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
34160 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
34170 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
34180 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
34190 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
341a0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
341b0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
341c0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
341d0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
341e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
341f0 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
34200 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
34210 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
34220 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73 69  .** The first si
34230 78 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62  x interfaces (_b
34240 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69  lob, _double, _i
34250 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78  nt, _int64, _tex
34260 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a  t, and _text16).
34270 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20 74  ** each return t
34280 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65  he value of a re
34290 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61  sult column in a
342a0 20 73 70 65 63 69 66 69 63 20 64 61 74 61 20 66   specific data f
342b0 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68  ormat.  If.** th
342c0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  e result column 
342d0 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79  is not initially
342e0 20 69 6e 20 74 68 65 20 72 65 71 75 65 73 74 65   in the requeste
342f0 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78  d format (for ex
34300 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65  ample,.** if the
34310 20 71 75 65 72 79 20 72 65 74 75 72 6e 73 20 61   query returns a
34320 6e 20 69 6e 74 65 67 65 72 20 62 75 74 20 74 68  n integer but th
34330 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
34340 5f 74 65 78 74 28 29 20 69 6e 74 65 72 66 61 63  _text() interfac
34350 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20  e.** is used to 
34360 65 78 74 72 61 63 74 20 74 68 65 20 76 61 6c 75  extract the valu
34370 65 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d  e) then an autom
34380 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72  atic type conver
34390 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
343a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
343b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
343c0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
343d0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
343e0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
343f0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
34400 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
34410 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
34420 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
34430 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
34440 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
34450 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
34460 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
34470 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
34480 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
34490 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
344a0 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  ]..** The return
344b0 20 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65   value of sqlite
344c0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
344d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
344e0 65 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f  ecide which.** o
344f0 66 20 74 68 65 20 66 69 72 73 74 20 73 69 78 20  f the first six 
34500 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64  interface should
34510 20 62 65 20 75 73 65 64 20 74 6f 20 65 78 74 72   be used to extr
34520 61 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76  act the column v
34530 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  alue..** The val
34540 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
34550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
34560 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
34570 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a  ningful if no.**
34580 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20   automatic type 
34590 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
345a0 20 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74 68   occurred for th
345b0 65 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74  e value in quest
345c0 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20  ion.  .** After 
345d0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
345e0 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  n, the result of
345f0 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
34600 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
34610 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20  * is undefined, 
34620 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e  though harmless.
34630 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
34640 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
34650 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
34660 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
34670 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
34680 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
34690 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
346a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  **.** If the res
346b0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
346c0 20 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20   a TEXT string, 
346d0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
346e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
346f0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ** or sqlite3_co
34700 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69  lumn_bytes16() i
34710 6e 74 65 72 66 61 63 65 73 20 63 61 6e 20 62 65  nterfaces can be
34720 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69   used to determi
34730 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f  ne the size.** o
34740 66 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  f that BLOB or s
34750 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tring..**.** ^If
34760 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34770 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
34780 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
34790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
347a0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
347b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
347c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
347d0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
347e0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
347f0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
34800 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
34810 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34820 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
34830 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
34840 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
34850 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
34860 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
34870 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
34880 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
34890 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
348a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
348b0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
348c0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
348d0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
348e0 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
348f0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
34900 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
34910 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
34920 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
34930 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
34940 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
34950 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
34960 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
34970 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
34980 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
34990 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
349a0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
349b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
349c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
349d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
349e0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
349f0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
34a00 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
34a10 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
34a20 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
34a30 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
34a40 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
34a50 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
34a60 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
34a70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
34a80 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
34a90 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
34aa0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
34ab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34ac0 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
34ad0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
34ae0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
34af0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
34b00 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
34b10 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
34b20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34b30 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
34b40 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
34b50 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
34b60 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
34b70 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
34b80 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
34b90 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
34ba0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
34bb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
34bc0 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
34bd0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34be0 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
34bf0 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
34c00 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
34c10 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
34c20 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
34c30 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
34c40 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
34c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34c60 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
34c70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
34c80 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
34c90 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
34ca0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
34cb0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
34cc0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
34cd0 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
34ce0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
34cf0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
34d00 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
34d10 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
34d20 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
34d30 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
34d40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
34d50 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
34d60 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
34d70 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
34d80 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
34d90 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
34da0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c  pointer..**.** <
34db0 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e  b>Warning:</b> ^
34dc0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
34dd0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
34de0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
34df0 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
34e00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
34e10 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e  lue] object.  In
34e20 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64   a multithreaded
34e30 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a   environment,.**
34e40 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
34e50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
34e60 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ject may only be
34e70 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74   used safely wit
34e80 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  h.** [sqlite3_bi
34e90 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
34ea0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34eb0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
34ec0 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
34ed0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34ee0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
34ef0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
34f00 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
34f10 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
34f20 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
34f30 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
34f40 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
34f50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
34f60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
34f70 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
34f80 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
34f90 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62  _bytes()], the b
34fa0 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74  ehavior is not t
34fb0 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65  hreadsafe..** He
34fc0 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  nce, the sqlite3
34fd0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20  _column_value() 
34fe0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
34ff0 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73  normally only us
35000 65 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20  eful within the 
35010 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
35020 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69  f .** [applicati
35030 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
35040 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69  unctions] or [vi
35050 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e  rtual tables], n
35060 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70  ot within.** top
35070 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69  -level applicati
35080 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54  on code..**.** T
35090 68 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  he these routine
350a0 73 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f  s may attempt to
350b0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74   convert the dat
350c0 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73  atype of the res
350d0 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61  ult..** ^For exa
350e0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
350f0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
35100 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
35110 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
35120 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
35130 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
35140 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
35150 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
35160 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
35170 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
35180 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
35190 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
351a0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
351b0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
351c0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
351d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
351e0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
351f0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
35200 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
35210 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
35220 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
35230 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
35240 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
35250 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
35260 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
35270 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
35280 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
35290 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
352a0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
352b0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
352c0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
352d0 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
352e0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
352f0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
35300 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
35310 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
35320 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
35330 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
35340 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
35350 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
35360 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
35370 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
35380 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
35390 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
353a0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
353b0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
353c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
353d0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
353e0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
353f0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
35400 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
35410 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
35420 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
35430 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
35440 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
35450 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
35460 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
35470 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
35480 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
35490 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
354a0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42  > [CAST] to BLOB
354b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
354c0 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
354d0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
354e0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
354f0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
35500 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
35510 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
35520 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
35530 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
35540 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
35550 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
35560 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
35570 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
35580 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
35590 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  R.** <tr><td>  B
355a0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
355b0 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
355c0 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
355d0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
355e0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
355f0 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
35600 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
35610 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
35620 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
35630 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ^.**.** Note tha
35640 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
35650 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
35660 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
35670 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
35680 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
35690 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
356a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
356b0 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
356c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
356d0 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
356e0 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
356f0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
35700 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
35710 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
35720 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
35730 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
35740 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
35750 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
35760 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
35770 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
35780 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
35790 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
357a0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
357b0 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
357c0 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
357d0 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
357e0 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
357f0 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
35800 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
35810 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
35820 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
35830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35840 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
35850 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35860 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
35870 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
35880 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
35890 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
358a0 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
358b0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
358c0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
358d0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
358e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
358f0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
35900 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35910 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
35920 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
35930 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
35940 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
35950 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
35960 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
35970 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
35980 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
35990 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
359a0 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
359b0 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
359c0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
359d0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
359e0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
359f0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
35a00 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
35a10 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
35a20 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
35a30 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
35a40 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
35a50 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
35a60 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
35a70 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
35a80 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
35a90 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
35aa0 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
35ab0 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
35ac0 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
35ad0 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
35ae0 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69   safest policy i
35af0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
35b00 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
35b10 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
35b20 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
35b30 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
35b40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35b50 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
35b60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35b70 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
35b80 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
35b90 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
35ba0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
35bb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
35bc0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
35bd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
35be0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
35bf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35c00 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
35c10 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
35c20 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
35c30 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
35c40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
35c50 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
35c60 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
35c70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35c80 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
35c90 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
35ca0 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
35cb0 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
35cc0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
35cd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35ce0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
35cf0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
35d00 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
35d10 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
35d20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
35d30 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
35d40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
35d50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35d60 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
35d70 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
35d80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35d90 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
35da0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
35db0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
35dc0 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
35dd0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
35de0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
35df0 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
35e00 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
35e10 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
35e20 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
35e30 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
35e40 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
35e50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
35e60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
35e70 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
35e80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
35e90 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
35ea0 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
35eb0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
35ec0 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
35ed0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
35ee0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f  atically.  Do no
35ef0 74 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  t pass the point
35f00 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
35f10 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
35f20 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
35f30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35f40 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
35f50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
35f60 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
35f70 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
35f80 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
35f90 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
35fa0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
35fb0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
35fc0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
35fd0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
35fe0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
35ff0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
36000 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
36010 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
36020 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
36030 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
36040 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
36050 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
36060 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
36070 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
36080 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
36090 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
360a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
360b0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
360c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
360d0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
360e0 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  PI double sqlite
360f0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
36100 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36110 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
36120 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36130 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
36140 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36150 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
36160 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
36170 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
36180 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
36190 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
361a0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
361b0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
361c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
361d0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
361e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
361f0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
36200 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
36210 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
36220 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36230 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
36240 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
36250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
36260 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
36270 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
36280 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36290 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
362a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
362b0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
362c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
362d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
362e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
362f0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
36300 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36310 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
36320 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36330 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
36340 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
36350 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
36360 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
36370 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
36380 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
36390 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
363a0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
363b0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
363c0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
363d0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
363e0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
363f0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
36400 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
36410 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
36420 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
36430 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
36440 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
36450 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
36460 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
36470 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
36480 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
36490 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
364a0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
364b0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
364c0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
364d0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
364e0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
364f0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
36500 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
36510 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
36520 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
36530 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
36540 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
36550 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
36560 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
36570 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
36580 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
36590 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
365a0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
365b0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
365c0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
365d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
365e0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
365f0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
36600 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
36610 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
36620 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
36630 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
36640 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
36650 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
36660 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
36670 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
36680 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
36690 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
366a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
366b0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
366c0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
366d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
366e0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
366f0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
36700 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
36710 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
36720 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36730 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
36740 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
36750 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
36760 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
36770 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
36780 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
36790 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
367a0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
367b0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
367c0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
367d0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
367e0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
367f0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
36800 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
36810 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
36820 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
36830 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
36840 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
36850 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
36860 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
36870 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45  ent Object.** ME
36880 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
36890 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  mt.**.** The sql
368a0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
368b0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
368c0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
368d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
368e0 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
368f0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
36900 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
36910 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
36920 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
36930 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
36940 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
36950 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
36960 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
36970 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
36980 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
36990 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
369a0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
369b0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
369c0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
369d0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
369e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
369f0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
36a00 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
36a10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
36a20 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
36a30 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
36a40 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
36a50 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
36a60 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
36a70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
36a80 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
36a90 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
36aa0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
36ab0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
36ac0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
36ad0 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
36ae0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
36af0 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
36b00 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
36b10 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
36b20 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
36b30 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
36b40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
36b50 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
36b60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
36b70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
36b80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36b90 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
36ba0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
36bb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
36bc0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
36bd0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
36be0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
36bf0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
36c00 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
36c10 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
36c20 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
36c30 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
36c40 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
36c50 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
36c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36c70 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50   S..*/.SQLITE_AP
36c80 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
36c90 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
36ca0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
36cb0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
36cc0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
36cd0 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
36ce0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
36cf0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
36d00 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
36d10 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
36d20 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
36d30 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
36d40 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
36d50 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
36d60 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
36d70 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d80 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
36d90 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
36da0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
36db0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
36dc0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
36dd0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
36de0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
36df0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
36e00 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
36e10 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
36e20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
36e30 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
36e40 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
36e50 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
36e60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
36e70 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
36e80 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
36e90 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
36ea0 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
36eb0 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
36ec0 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
36ed0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
36ee0 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
36ef0 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
36f00 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
36f10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
36f20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
36f30 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
36f40 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
36f50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36f60 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
36f70 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
36f80 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
36f90 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
36fa0 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
36fb0 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
36fc0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
36fd0 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
36fe0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
36ff0 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
37000 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
37010 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37020 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
37030 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
37040 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
37050 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
37060 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
37070 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
37080 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
37090 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
370a0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
370b0 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
370c0 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
370d0 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
370e0 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
370f0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
37100 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
37110 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
37120 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
37130 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
37140 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
37150 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
37160 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
37170 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
37180 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
37190 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
371a0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
371b0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
371c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
371d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
371e0 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
371f0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
37200 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
37210 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
37220 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
37230 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
37240 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
37250 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
37260 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
37270 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
37280 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
37290 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
372a0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
372b0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
372c0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
372d0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
372e0 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
372f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
37300 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
37310 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
37320 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
37330 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
37340 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
37350 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
37360 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
37370 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
37380 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
37390 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
373a0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
373b0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
373c0 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
373d0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
373e0 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
373f0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
37400 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
37410 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
37420 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
37430 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
37440 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
37450 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
37460 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
37470 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
37480 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
37490 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
374a0 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
374b0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
374c0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
374d0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
374e0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
374f0 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
37500 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
37510 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
37520 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
37530 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
37540 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
37550 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
37560 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
37570 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
37580 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
37590 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
375a0 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
375b0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
375c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
375d0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
375e0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
375f0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
37600 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
37610 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
37620 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
37630 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
37640 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
37650 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
37660 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
37670 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
37680 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
37690 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
376a0 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
376b0 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
376c0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
376d0 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
376e0 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
376f0 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
37700 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
37710 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
37720 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
37730 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
37740 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
37750 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
37760 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
37770 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
37780 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
37790 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
377a0 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
377b0 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
377c0 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
377d0 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
377e0 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
377f0 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
37800 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
37810 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
37820 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
37830 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
37840 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
37850 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
37860 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
37870 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
37880 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
37890 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
378a0 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
378b0 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
378c0 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
378d0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
378e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
378f0 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
37900 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
37910 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
37920 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
37930 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
37940 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
37950 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
37960 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
37970 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
37980 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
37990 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
379a0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
379b0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
379c0 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
379d0 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
379e0 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
379f0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
37a00 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
37a10 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
37a20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
37a30 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
37a40 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
37a50 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
37a60 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
37a70 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
37a80 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
37a90 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
37aa0 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
37ab0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
37ac0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
37ad0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
37ae0 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
37af0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
37b00 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
37b10 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
37b20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
37b30 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
37b40 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
37b50 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
37b60 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
37b70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
37b80 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
37b90 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
37ba0 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
37bb0 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
37bc0 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
37bd0 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
37be0 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
37bf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37c00 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
37c10 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
37c20 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
37c30 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
37c40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37c50 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
37c60 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
37c70 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
37c80 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
37c90 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
37ca0 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
37cb0 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
37cc0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
37cd0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
37ce0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
37cf0 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
37d00 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
37d10 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
37d20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
37d30 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
37d40 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
37d50 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
37d60 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
37d70 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
37d80 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
37d90 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
37da0 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
37db0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
37dc0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
37dd0 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
37de0 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
37df0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
37e00 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
37e10 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
37e20 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
37e30 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
37e40 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
37e50 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
37e60 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
37e70 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
37e80 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
37e90 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
37ea0 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
37eb0 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
37ec0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
37ed0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
37ee0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
37ef0 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
37f00 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
37f10 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
37f20 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
37f30 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
37f40 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
37f50 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
37f60 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
37f70 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
37f80 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
37f90 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
37fa0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
37fb0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
37fc0 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
37fd0 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
37fe0 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
37ff0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
38000 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
38010 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
38020 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
38030 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
38040 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
38050 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
38060 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
38070 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
38080 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
38090 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
380a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
380b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
380c0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
380d0 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
380e0 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
380f0 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
38100 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
38110 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
38120 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
38130 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
38140 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
38150 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
38160 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
38170 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
38180 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
38190 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
381a0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
381b0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
381c0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
381d0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
381e0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
381f0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
38200 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
38210 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
38220 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
38230 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
38240 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
38250 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
38260 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
38270 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
38280 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
38290 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
382a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
382b0 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
382c0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
382d0 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
382e0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
382f0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
38300 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
38310 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
38320 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38330 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
38340 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
38350 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
38360 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
38370 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
38380 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
38390 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
383a0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
383b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
383c0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
383d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
383e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
383f0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
38400 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
38410 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
38420 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
38430 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
38440 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
38450 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
38460 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
38470 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
38480 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
38490 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
384a0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
384b0 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
384c0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
384d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
384e0 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
384f0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
38500 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
38510 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
38520 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
38530 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
38540 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
38550 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
38560 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
38570 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
38580 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33  1    /* IMP: R-3
38590 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64  7514-35566 */.#d
385a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
385b0 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20  16LE        2   
385c0 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31   /* IMP: R-03371
385d0 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e  -37637 */.#defin
385e0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
385f0 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20          3    /* 
38600 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31  IMP: R-51971-341
38610 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  54 */.#define SQ
38620 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
38630 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
38640 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
38650 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
38660 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
38670 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65     5    /* Depre
38680 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  cated */.#define
38690 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
386a0 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
386b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
386c0 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
386d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 4